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PREFACE 


Primary reference material for user and subsystem programming on the 
Multics system is contained in five manuals. The manuals are collectively 
referred to as the Multics Programmers' Manual (MPM). Throughout this manual, 


references are frequently made to the MPM. For convenience, these references 
will be as follows: 


Document Referred To In Text As 


Reference Guide MPM Reference Guide 


(Order No. AGQ1) 


Commands and Active Functions MPM Commands 
(Order No. AGQ92) 


Subroutines MPM Subroutines 
(Order No. AG93) 


Subsystem Writers' Guide MPM Subsystem Writers! Guide . 
(Order No. AK92) | 
Peripheral Input/Output MPM I/0 


(Order No. AX49) 


The MPM Reference Guide contains general information about the Multics 
command and programming environments. It also defines items used throughout the 
rest of the MPM. And, in addition, describes such subjects as the command 
language, the storage System, and the input/output system. 


The MPM Commands is organized into four’ sections. Section I contains a 
list of the Multics command repertoire, arranged functionally. It also contains 
a discussion on constructing and interpreting names. Section II describes the 
active functions. Section III contains descriptions of standard Multics 
commands, including the calling sequence and usage of each command. Section IV 
describes the requests used to gain access to the system. 


The MPM Subroutines is organized into three sections. Section I contains a 


list of the subroutine repertoire, arranged functionally. Section II contains 
descriptions of the standard Multics Subroutines, including the declare 
Statement, the calling sequence, and usage of each. Section III contains the 


descriptions of the I/O modules. 


The MPM Subsystem Writers' Guide is a reference of interest to compiler 
writers and writers of Sophisticated subsystems. It documents’ user-accessible 
modules that allow the user to bypass standard Multics facilities. The 
interfaces thus documented are a level deeper into the system than those 
required by the majority of users. : 
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The MPM I/0 manual contains descriptions of commands and subroutines used 
to perform peripheral I/0. Included in this manual are commands and subroutines 
that manipulate tapes and disks as I/O devices. Special purpose communications 
I/O, such as binary synchronous communication, is also included. 


Examples of specialized subsystems for which construction would require 
reference to the MPM Subsystem Writers! Guide are: 


® A subsystem that precisely imitates the command environment of some 
system other than Multics. 


e A subsystem intended to enforce restrictions on the services available 
to a set of users (e.g., an APL-only subsystem for use in an academic 
class). 


@ A subsystem that protects some kind of information in a way not’ easily 
expressible with ordinary access control lists (e.g., a proprietary 
linear programming system, or an administrative data base system that 
permits access only to program-defined, aggregated information such as 
averages and correlations). 


The MPM Subsystem Writers' Guide provides the advanced Multies user with a 
selection of some of the internal interfaces used to construct the standard 
Multies user interface. It also describes some specialized tools helpful to the 
advanced subsystem writer. 


The facilities described here are subject to changes and improvements in 
their interface specifications. Further, at the level of the system presented 
by many of these interfaces, it is difficult to avoid far-reaching sybsystem 
changes when these interfaces change. Thus, the sybsystem writer is cautioned 
against the unnecessary use of the interfaces described in this manual. 


Most interfaces described here should be used only if there is a need to 
bypass normal Multics procedures; i.e., in using one of these interfaces, the 
user risks giving up some of the desirable characteristics of Multics. For 
example, the standard Multics interface presents a consistency of style and 
interpretation to the user that the subsystem writer may find difficult to 
duplicate and maintain. Therefore, the subsystem writer should be cautious 
about unintentionally introducing different, and possibly confusing, styles and 
interpretations when bypassing a standard function. 


However, one of the objectives of Multics is to allow the knowledgable user 
to construct subsystems of almost any specification. The content of the MPM 
Subsystem Writers' Guide, applied with care, is intended to help fulfill this 
objective. 


Several cross-reference facilities in the MPM help locate information: 


® Fach manual has a table of contents that identifies the material 
(either the name of the section and subsection or an alphabetically 
ordered list of command and subroutine names) by page number. — 


@ ‘Fach manual contains an index that lists items by name and page number. 
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SECTION I 


MULTICS STANDARD OBJECT SEGMENT 


A Multics object segment contains object code generated by a translator and 
linkage information that is used by the dynamic linking mechanism to resolve 
intersegment references. (See "Dynamic Linking" in the MPM Reference Guide.) 
The most common examples of object segments are procedure segments and data 
segments. , 


Format requirements for an object segment are primarily associated with 
external interfaces; thus, translator designers are permitted a great amount of 
freedom in the area of code and data generation. The format contains certain 
redundancies and unusual data structures; these are a byproduct of maintaining 
upward compatibility with earlier object segment formats. The dynamic linking 
mechanism and the standard object segment manipulation tools assume that all 
object segments are standard object segments. 


FORMAT OF AN OBJECT SEGMENT 


An object segment is divided into six sections that usually appear in the 
following order: 


text 

definition 

linkage 

static (if present) 
symbol 

break map (if present) 


The type of information contained in each of the six sections is summarized 
below: 


Wg text contains only pure parts of the object segment 
(instructions and read-only data). It can also contain 
relative pointers to the definition, linkage and symbol 
sections. 


2 definition contains only nonexecutable, read-only symbolic 
information used for dynamic linking and _ symbolic 
debugging. Since it is assumed that the definition 
section is infrequently referenced (as opposed to the 
constantly referenced text section), it should not be 
used as a repository for read-only constants referenced 
during the execution of the text section. The 
definition section can sometimes (as in the case of an 
object segment generated by the binder) be structured 
into definition blocks that are threaded together. 


1-1 AKY92 


3. linkage contains the impure (i.e., modified during the 
program's execution) nonexecutable parts of the object 
Segment and may consist of two types of data: 


a. links modified at run time by the Multics linker 
: to contain the machine address of external 
references, and possibly 


b. data items to be allocated on a per-process' basis 
such as the internal static storage of PL/I 
procedures. 


4, static contains the data items to be allocated on a 
per-process basis. The static storage may be included 
in the linkage section in which case there is no 
explicit separate static section. 


Ds break map contains information used by the debuggers to locate 
breakpoints in the object segment. This section is 
generated by the debuggers rather than the translator 
and only when the segment currently contains 
breakpoints. Its internal format is of interest only 
to the debuggers. 


6. symbol contains all generated items of information that do not 
belong in the first five sections such as the language 
processor's symbol tree and historical and relocation 
information. The symbol section may be further 
structured into variable length symbol blocks’ threaded 
to forma list. The symbol section contains only pure 
information. | 


The text, definition, and symbol sections are shared by all processes’. that 
reference an object segment. Usually, a copy of the linkage section is made 
when an object segment is first referenced in a process. That is, the linkage 
section is a per-process data base. The original linkage section serves only as 
a copying template. An exception is made for some system programs whose link 
addresses are filled in at system initialization time. Their linkage sections 
are shared by everyone who wants to use the supplied addresses. When these 
programs have data items in internal storage, they have a_ separate static 
section template that is copied once per process. See "Dynamic Linking" in the 
MPM Reference Guide and "Standard Stack and Linkage Area Formats" in Section II 
of this document. Normally, a segment containing break map information is in 
the state of being debugged and is not used by more than one process. 


The object segment also contains an object map that contains the offsets 
and lengths of each of the sections. The object map can be located immediately 
before or immediately after any of the six sections. Translators normally place 
it immediately after the symbol section. The last word of every object segment 
must contain a left-justified 18-bit relative pointer to the object map. 


STRUCTURE OF THE TEXT SECTION 


The text section is basically unstructured, containing the machine-language 
representation of a symbolic algorithm and/or pure data. Its length is usually 
an even number of words. 


Two of the items that can appear within the text section have standard 
formats: the entry sequence and the gate segment entry point transfer vector. 
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Entry sequence 


A standard entry 
accessible procedure 


normally contiguous): 


del parm_desc_pt 


1 
2 n_args 
2 


sequence 
entry point 


rs 


descriptor_relp(n_args) 


del 
descr_relp_o 
reserved 
def_relp 
flags 

3 basic_indi 
3 revision_1 
3 has_descri 
3 variable 
3 
3 
C 


NM PoP Po => 


function 
pad . 


2. descriptor_relp 


3. descr_relp_offset 
4. reserved 


5. def_relp 


6. flags 
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entry_sequence 


ffset 


ecator 


ptors 


is usually provided for every externally 
in an object segment. A standard entry 
sequence has the following format (the two structures are independent but 


aligned, 


bit(18) unaligned, 
bit(18) unaligned; 


aligned, 

bit(18) unaligned, 
bit(18) unaligned, 
bit(18) unaligned, 
unaligned, 

bit(1) unaligned, 
bit(1) unaligned, 
bit(1) unaligned, 


‘bit(1) unaligned, 
~bit(1) unaligned, 


ode_sequence(n) 


is the number of arguments expected 


entry point. This item is optional and is valid only 


bit(13) unaligned, 
bit(36) aligned; 


if the flag has_descriptors equals "1"b. 


is an array of pointers (relative to the base of 
text section) 


is the offset (relative to the base of the 


section) of the n_args item. 


are 


by this external 


the 
to the descriptors of the corresponding 
entry point parameters. This item is optional and 
valid only if the flag has_descriptors equals "1"b. 


is 


text 
This item is optional and 


is valid only if the flag has_descriptors equals "1"b. 


is reserved for future use and must be "0"b. 


is an offset (relative to the base of the definition 
Thus, 
to 


section) 


given a pointer to an entry point, it is possible 
reconstruct its symbolic name for purposes such as 


to the definition of this entry point. 


diagnostics or debugging. 


contains 1 


8 binary indicators that provide information 


about this entry point. 


basic_indicator 


Le Le @) 
"ONhH 


revision_1 
m1! b 


"mOMb 


this is the entry point of a BASIC program 
BASIC 


this is not the entry point of a 
program 


all of the entry's parameter descriptor 


information is with the entry sequence, 


i.e., none is in the definition 
parameter descriptor information, if 
is with the definition 
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any, 
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has_descriptors 
we) the entry has parameter descriptors; i.e., 
items n_args, descriptor_relp and 
descr_relp_offset contain valid information 
"O"b the entry does not have parameter 
descriptors 


variable 
a ele the entry expects arguments whose number 
and types are variable 
"Ob the number and type of arguments, if any, 
are not variable 


function 
ED the last parameter is to be returned by 
this entry 
TO" the last parameter is not to be returned by 
this entry 
pad is reserved for future use and must be "0"b 
7. code_sequence is any sequence of machine instructions satisfying 


Multics standard calling conventions. See "Subroutine 
Calling Sequences" in Section II. 


The value (i.e., offset within the text section) of the entry point 
corresponds to the address of the code_sequence item. (The value is stored in 
the formal definition of the entry point. See "Structure of the Definition" 
below.) Thus, if entry_offset is the value of the entry point ent1, then the 
def_relp item pointing to the definition ‘for ent1l is located at word 
(entry_offset minus 1). | 


Gate Segment En Point Tran V 


For protection purposes, control must not be passed to a gate procedure at 
other than its defined entry points. To enforce this restriction, the first n 
words of a gate segment with n entry points must be an entry point transfer 
vector. That is, the kth word (0 < k < n-1) must be a transfer instruction to 
the kth entry point (i.e., a transfer to the code_sequence item of a standard 
entry sequence as described above). In this case, the value of the kth entry 
point is the offset of the kth transfer instruction (i.e., word k of the 
segment) rather than the offset of the code_sequence item of tthe kth entry 
point. 


To ensure that only these entries can be used, the hardware enforced entry 


bound of the gate segment must be set so that the segment can be entered only at 
the first n locations. 
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STRUCTURE OF THE DEFINITION SECTION 


The definition section of an object segment contains pure information that 
is used by the dynamic linking mechanism. 


The definition section consists of a header pointing to a linked list of 
items describing the externally accessible named items of the object segment, 
followed by an unstructured area containing information describing the 
externally accessible named items of other object segments referenced by this 
object segment. The linked list is known as the definition list. The items on 
the list are known as definitions. The unstructured area contains expression 
words, type pairs, trap pairs, trap procedure information, and the symbolic 
names associated with external references. 


A definition specifies the name of an externally accessible named item and 
its location in the object segment. The definition list consists of one or more 
definition blocks each of which consists of one or more class-3 definitions 
followed by zero or more definitions that are not class-3 (see "Definition 
Section Header" below for format). Normally, unbound object segments contain 
one definition block, while bound segments contain one definition block for 
every component object segment. 


The information in the unstructured area of the definition section is used 
at runtime in conjunction with information in the linkage section to resolve the 
external references made by the object segment. This information is 
conceptually part of the linkage section, but is stored in the definition 
section so it can be shared among all the users of the segment. 


Figure 1-1 shows the structure of the definition section. For more 
information concerning the interpretation of the information in the definition 
section see "Dynamic Linking" in the MPM Reference Guide. 


Character strings in the definition section are stored in ALM "acc" format. 
This format is defined by the following PL/I declaration: 


del 1 ace aligned, 
2 length_of_string fixed bin(8) unaligned, 
2 string char(0 refer(length_of_string)) unaligned; 


The first nine bits of the string contain the length of the _ string. such a 
structure is referred to as an acc string. 


The following paragraphs describe the formats of the various items in the 
definition section. 
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def_list_relp eee eee Header 


class - 3 
~ defblock _ ptr 


Block ? 


backward 
class = 3 
detixock _ » 


backward i 
class = 3 
defblock _ ptr 


a ee 


Block 3 


all zero word 


Figure 1-1. Sample Definition List 
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Definition Section Header 


The definition section header resides at the base of the definition section 
and contains an offset (relative to the base of the definition section) to the 


beginning of the definiti 


del 1 def_header 
2 def_list_relp 
2 unused 
2 flags 
3 new_format 
3 ignore 
3 unused 


where: 


Ts def_list_relp 


on list. 


aligned, 

bit(18) unaligned, 

bit(36) unaligned, 
unaligned, 

bit(1) unaligned initial (" 
bit(1) unaligned initial (" 
bit(16) unaligned; 


is a relative pointer to the 


definition list. 


Ce unused is 


3% flags 


reserved for future use and 


contains 18 binary indicators 


about this definition section: 


new_format 


Li Le) definition section 
"QMb definition section 


ignore 


unu 


wTNb if new_format equa 
ignores this defin 
"OND is an old format d 


sed is reserved for fu 


1"b), 
1"b), 


first definition in the 


must be "O"b, 


that provide information 


has new format 
has old format 


ls "1"b, the Multics linker 
ition. 
efinition 


ture use and must be "O"b 


The format of a definition that is not class-3 is given below. 


del definition 


aligned, 


1 
2 forward_thread 
2 backward_thread 
2 value 
2 flags 
3 new_format 
3 ignore 
3 entry_point 
3 retain 
3 
3 
3 


argcount 


has_descriptors 


unused 
class | 
symbol_relp 
segname_relp 
n_args 


MMPND . 
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descriptor_relp (0 refer(n_args) 


bit(18) unaligned, 
bit(18) unaligned, 
bit(18) unaligned, 
unaligned, 

bit(1) unaligned, 

bit(1) unaligned, 

bit(1) unaligned, 

bit(1) unaligned, 

bit(1) unaligned, 

bit(1) unaligned, 

bit(9) unaligned, 


bit(3) unaligned, 
bit(18) unaligned, 
bit(18) unaligned, 
bit(18) unaligned, 
bit(18) unaligned; 
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where: 


Ve forward_thread 


rage backward_thread 


3% value 


4, flags 


5; class 


6. symbol_relp 
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is a thread (relative to the base of the definition 
section) to the next definition. The thread terminates 
when it points to a word that is 0. This thread provides 
a Single sequential list of all the definitions within the 
definition section. 


is a thread (relative to the base of the definition 
section) to the preceding definition. 


is the offset, within the section designated by the class 
variable (described below), of this symbolic definition. 


contains 15 binary indicators that provide additional 
information about this definition: 


new_format 
"1"b definition section has new format 
"OND definition section has old format 


ignore 
i ia ©) definition does not represent an external 
symbol and is, therefore, ignored by the 
Multics linker 
OUD definition represents an external symbol 


entry_point 
"1"b definition of an entry point (a variable 
reference through a transfer of control 
instruction) | 
"Ob definition of an external symbol that does not 
represent a standard entry point 


retain 
we definition must be retained in the object 
segment (by the binder) 
"O"b definition can be deleted from the object 
segment (by the binder) 


argcount 
nq7Mh (obsolete) definition includes a count of the 
argument descriptors (i.e., item n_args below 
contains valid information) 
"Ob no argument descriptor information is 
associated with the definition 


has_descriptors 


n1"b (obsolete) definition includes an array of 
argument descriptor (i.e., items n_args and 
descriptor_relp below contain valid 
information) 


"O"b no valid descriptors exist in the definition 
unused is reserved for future use and must be "0"b 


this field contains a code indicating the section of the 

object segment to which value is relative. Codes are: 
text section 

1 linkage section 

2 symbol section 

3 this symbol is a segment name 

4 Static section 


is an offset (relative to the base of the definition 


section) to an aligned acc string representing the 
definition's symbolic name. 
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Ts segname_relp is an offset (relative to the base of the definition 
section) to the first class-3 definition of this 
definition block. 


8. n_args (obsolete) is the number of arguments expected by this 
external entry point. This item is present only if 
argecount or has_descriptors equals "1"b. 


9. descriptor_relp (obsolete) is an array of pointers (relative to the base 
of the text section) that point to the descriptors of the 
corresponding entry point arguments. This item is present 
only if has_descriptors equals "1"b. 


The obsolete items are described here to illustrate earlier versions; 
translators should put these items in the entry sequence of the text section. 
See "Entry Sequence" above. 


In the case of a class-3 definition, the above structure is interpreted as 
follows: | 


del 1 segname aligned, 

2 forward_thread bit(18) unaligned, 
2 backward_thread bit(18) unaligned, 
2 segname_thread bit(18) unaligned, 
2 flags bit(15) unaligned, 
2 class bit(3) unaligned, 
2 symbol_relp bit(18) unaligned, 
2 first_relp bit(18) unaligned; 

where: 

1. forward_thread is the same as above. 

os backward_thread is the same as above. 


3% segname_thread is a thread (relative to the base of the definition 
| section) to the next class-3 definition. The thread 
terminates when it points to a word that contains all O's. 
This thread provides a single sequential list of all 

class-3 definitions in the object segment. 


4, flags is the same as above. 

5. class is the same as above (and has a value of 3). 

6. symbol_relp is the same as above. 

le first_relp | is an offset (relative to the base of the definition 
section) to the first nonclass-3 definition of the 


definition block. If the block contains no _  nonclass-3 
definitions, it points to the first class-3 definition of 
the next block. If there is no next block, it points toa 
word that is all O's. 
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The end of a definition block is determined by one of the following 
conditions (whichever comes first): 


les forward_thread points to an all zero word; ; 


2% the current entry's class is not 3, and forward_thread points to a 
class-3 definition; 


Sia the current definition is class 3, and both forward_thread and 
first_relp point to the same class-3 definition. 


The threading of definition entries is shown in Figure 1-1 above. The 
following paragraphs describe items in the unstructured portion of the 
definition section. 


Expression Word 


The expression word is the item pointed to by the expression pointer of an 
unsnapped link (see "Structure of the Linkage Section" below) and has the 


following structure: 


del 1 exp_word aligned, 
2 type_pair_relp bit(18) unaligned, 
2 expression fixed bin(17) unaligned; 
where: 


mn 


ae type_pair_relp is an offset (relative to the base of the definition 
section) to the link's type pair. J 


2% expression is a signed value to be added to the offset (i.e., offset 
within a segment) of the resolved link. 


e Pair 


The type pair is a structure that defines the external symbol pointed to by 
a link. 


type_pair aligned, 


del 1 | 
2 type bit(18) unaligned, 
2 trap_relp bit(18) unaligned, 
2 segname_relp bit(18) unaligned, 
2 offsetname_relp bit(18) unaligned; 
where: 


1s type assumes a value from 1 to 6: 
| 1 isa self-referencing link (i.e., the segment in which 
the external symbol is located is the object segment 


containing this link or a dynamic related section of 
the link) of the form: 


myself |0+expression,modifier 
2 unused; it was earlier used to define a now obsolete 


ITP-type link. 
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trap_relp 


segname_relp 


offsetname_relp 


3 is a link referencing a specified reference name but no 
symbolic offset name, of the form: 


refname |0+expression,modifier 


4 is a link referencing both a symbolic reference name 
and a symbolic offset name, of the form: 


refname ;offsetname+expression,modifier 


5 is a self-referencing link having a_ symbolic offset 
name, of the form: 


myself ;joffsetname+expression,modifier 


6 same as type 4 except that the external item is created 
if it is not found. (See "Dynamic Linking" in the MPM 
Reference Guide.) (Now Obsolete. ) 


is an offset (relative to the base of the definition 
section) to either an initialization structure (if type 
equals 5 and segname_relp equals 5 or if type equals 6) or 
to a trap pair. 


is a code or a pointer depending on the value of type. 
For types 1 and 5, this item is a code that can assume one 
of the following values, designating the sections of the 
self-referencing object segment: 


is a self-reference to the object's text section; such a 
reference is represented'symbolically as "text". 


is a self-reference to the object's linkage section; such 
a reference is represented symbolically as "*®link". 


is a self-reference to the object's symbol section; such a 
reference is represented symbolically as "*symbol". 


is a self-reference to the object's static section; such a 
reference is represented symbolically as "*static". 


is a reference to an external variable managed by the 


linker; such a reference is represented symbolically as 
"system", | 


For types 3, 4, and 6, this item is an offset (relative to 
the base of the definition section) to an aligned acc 
string containing the reference name portion of an 
external reference. (See "Constructing and Interpreting 
Names" in Section III of the MPM Reference Guide.) 


has a meaning depending on the value of type. For types 1 
and 3, this value is ignored and must be zero. For types 
4, 5, and 6, this item is an offset (relative to the base 
of the definition section) to an aligned ace string of an 
external reference. (See "Constructing and Interpreting 
Names" in Section III of the MPM Reference Guide for a 
discussion of offset names.) 
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Trap Pair 


The trap pair is a structure that specifies a trap procedure to be called 
before the link associated with the trap pair is resolved by the dynamic linking 
mechanism. It consists of relative pointers to two links. (Links are defined 
under "Structure of the Linkage Section" below.) The first link defines the 
entry point in the trap procedure to be called. The second link defines a block 
of information that is passed as one of the arguments of the trap procedure. 
For more detailed information on trap procedures see "Dynamic Linking" in the 
MPM Reference Guide. The trap pair is structured as follows: 


del 1 trap_pair aligned, 
2 entry_relp bit(18) unaligned, 
2 info_relp bit(18) unaligned; 
where: 


Vs entry_relp is an offset (relative to the base of the linkage section) to a 
link defining the entry point of the trap procedure. 


2; info_relp is an offset (relative to the base of the linkage section) to a 
link defining information of interest to the trap procedure. 


Initializati Str re f T #5 mand Type 6 Link 


This structure specifies how a link target first referenced because of a 
type 5 *system or a type 6 link should be initialized. It has the following 
format: | 


del 1 initialization_info aligned, 


2 n_words fixed bin, 
2 code fixed bin, 
2 info (n_words) bit(36) aligned; 
where: 
Vs n_words is the number of words required by the new variable. 
Le code indicates what type of initialization is to be performed. It 
can have one of the following values: | 
0 no initialization is to be performed 
5° copy the info array into the newly defined variable 
4 initialize the variable as an area 
35 info is the image to be copied into the new variable. It exists 


only if code is 3. 


STRUCTURE OF THE STATIC SECTION 


The static section is unstructured. 
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STRUCTURE OF THE LINKAGE SECTION 
The linkage section is subdivided into four distinct components: 


a A fixed-length header that always resides at the base of the linkage 
section 


2. A variable length area used for internal (static) storage (optional) 
3% A variable length structure of links (optional) 


4, First-reference trap (optional) 


These four components) are located within the linkage section in the following 
sequence: 


header 

internal storage (if present) 
links (if present) 

trap (if present) 


The length of the linkage section must be an even number of words and must 
start on an even -word boundary; in addition, the link substructure must also 
begin at an even location (offset) within the linkage section. 


{ 


When an object segment is first referenced in a process, its linkage 
section is copied into a per-process data base. At this time certain items in 
the copy of the header are initialized. Items not explicitly described as being 
initialized by the linker are set by the program that generates the object 
segment. In addition, the first two words of the header (containing the items 
pad, def_section_relp, and first_reference_relp) are overwritten with a pointer 
to the beginning of the object segment's definition section. For more 
information see "Dynamic Linking" in the MPM Reference Guide and "Standard Stack 
and Linkage Area Formats" in Section II of this manual. 


ge Sec Header 


The header of the linkage section has the following format: 


del 1 linkage_header aligned, 

2 pad bit(36), 

2 def_section_relp bit(18) unaligned, 

2 first _reference_relp bit(18) unaligned, 

2 symbol_ptr ptr unal, 

2 original_linkage_ptr ptr unal, 

2 unused bit(72), 

2 links_relp bit(18) unaligned, 

2 linkage_section_length bit(18) unaligned, 

2 object_segno bit(18) unaligned, 

2 static_length bit(18) unaligned; 
where: 
1 pad is reserved for future use and must be 0. 
2. def_section_relp is an offset (relative to the base of the object 


segment) to the base of the definition section. 
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Bs first_reference_relp is an offset (relative to the base of the linkage 
section) to the first-reference trap. This trap is 
activated by the linker when the first reference to 
this object segment is made within a given process. 
If the value of this item is "0"b, there is no 
first-reference trap. 


4, symbol_ptr is a pointer to the object segment's symbol 
section. It is used by the linker to snap links 
relative to the symbol section. It is initialized 
by the linker when the header is copied. 


D's Original_linkage_ptr is a pointer to the original linkage section within 
the object segment. It is used by the link 
unsnapping mechanism and is initialized by the 
linker when the header is copied. 


6. links_relp | is an offset (relative to the base of the linkage 
section) to the first link (the base of the link 
array). 

te linkage_section_length is the entire length in words of the entire linkage 
section. 

8. object_segno is the segment number of the object segment. It is 
initialized by the linker when the header is 
copied. 

9. static_length is the length in words of the static section and is 


valid even when static is part of the linkage 
section. It is initialized by the linker if not 
filled in by the translator. 


Internal St e Are 


The internal storage area is an array of words used by translators to 
allocate internal static variables and has no predetermined structure. 


Links 


A linkage section may contain an array of link pairs, each of which defines 
an external name, referenced by this object segment, whose effective address is 
unknown at compile time. Figure 1-2 illustrates the structure of a link. 


A link must reside on an even location in memory, and must therefore be 
located at an even offset from the base of the linkage section. The format of a 
link is: 


del 1 link aligned, 
2 header_relp bit(18) unaligned, 
2 ignorel bit(12) unaligned, 
2 tag bit(6) unaligned, 
2 expression_relp bit(18) unaligned, 
2 ignore2 bit(12) unaligned, 
2 modifier bit(6) unaligned; 
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where: 


leg header_relp is an offset (relative to the link itself) to the head of 
| the linkage section. It is, in other words, the negative 
value of the link pair's offset within the linkage 


section. 
2. ignorel is reserved for future use and must be "0O"b. 
35 tag is a constant (46)8 that represents — the hardware 


fault tag 2 and distinctly identifies an unsnapped link. 
The snapped link (ITS pair) has a distinct (43)8 tag. See 
"Simulated Fault" in Section VII of the MPM Reference 
Guide. 


4, expression_relp is an offset (relative to the base of the definition 
section) to the expression word for this link. 


Ds ignore2 is reserved for future use and must be "0"b. 


6. modifier is a hardware address modifier. 


irst-Reference Tra 


It is sometimes necessary to perform certain types of initialization of an 
object segment when it is first referenced for. execution (i.e., linked to) ina 
given process--for example, to store some per-process information in the segment 
before it is used. The first-reference trap mechanism provides this facility 
for use by various mechanisms, the status code assignment mechanism being an 
example. See "Handling of Unusual Occurrences" in Section VII of the MPM 
Reference Guide. 


A first-reference trap consists of two relative pointers. The first points 
to a link defining the first reference procedure entry point to be invoked. The 
second points to a link defining a block of information to be passed as an 
argument to the first-reference procedure. For more details on first-reference 
traps, see "Dynamic Linking" in the MPM Reference Guide. 


del 1 fr_traps aligned, 
| 2 decl_vers fixed bin initial(1), 
2 n_traps fixed bin, 
2 call_relp bit(18) unaligned, 
2 info_relp bit(18) unaligned; 
where: 
Is decl_vers is the version number of the structure. 
2% n_traps specifies the number of traps; it must equal 1. 
3% call_relp is an offset (relative to the base of the linkage section) 


to a link defining a procedure to be invoked by the linker 
upon first reference to this object within a given 
process. 


4, info _relp is an offset (relative to the base of the linkage section) 
to a link specifying a block of information to be passed 
as an argument to the first reference procedure; if 
info_relp is 0, there is no such block. 
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Figure 1-2. Structure of a Link 
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STRUCTURE OF THE SYMBOL SECTION 


The symbol section consists of one or moré symbol blocks threaded together 
to form a single list. A symbol block has two main functions: to document the 
circumstances under which the object segment was created, and to serve as a 
repository for information (relocation information, compiler's symbol tree, 
etc.) that does not belong in any of the other’ sections. 


The symbol section must contain at least one symbol block, describing the 
circumstances under which the object segment was created. A symbol section can 
contain more than one symbol block. An example of multiple symbol blocks is the 
case of a bound segment where in addition to the symbol block describing the 
Segment's creation by the binder, there is also a symbol block for each of the 
component object segments. 


A symbol block consists of a fixed length header and a variable length area 
pointed to by the header. The contents of this area depend on the symbol block. 
For example, a compiler's symbol block can contain a symbol tree, and _ the 
binder's symbol block contains the bind map. 


symbol Block Header 


All symbol blocks have a standard fixed-format header, although not all 
items in the header have meaning for all symbol blocks. The description of a 
particular symbol block lists items that have meaning for that symbol block. 
The header has the following format: 


del 1 symbol_block_header aligned, 
2 decl_vers fixed bin initial(1), 
2 identifier char(8) aligned, 
2 gen_version_number fixed bin, 
2 gen_creation_time fixed bin(71), 
2 object_creation_time fixed bin(71), 
2 generator char(8) aligned, 
2 gen_version_name_relp bit(18) unaligned, 
2 gen_version_name_length bit(18) unaligned, 
2 access_name_relp bit(18) unaligned, 
2 access_name_length bit(18) unaligned, 
2 comment_relp bit(18) unaligned, 
2 comment_length bit(18) unaligned, 
2 text_boundary bit(18) unaligned, 
2 stat_boundary bit(18) unaligned, 
2 source_map_relp bit(18) unaligned, 
2 area_relp | bit(18) unaligned, 
2 section_relp bit(18) unaligned, 
2 block_size bit(18) unaligned, 
2 next_block_thread bit(18) unaligned, 
2 text_relocation_relp bit(18) unaligned, 
2 def_relocation_relp bit(18) unaligned, 
2 link_relocation_relp bit(18) unaligned, 
2 symbol_relocation_relp bit(18) unaligned, 
2 default_truncate bit(18) unaligned, 
2 optional_truncate bit(18) unaligned; 
where: 
1. decl_vers is the version number of the structure. 
2. identifier is a symbolic name identifying the type of symbol 
block. 
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10. 


le. 


15. 


1p 


gen_version_number 


gen_creation_time 
object_creation_time 
generator 


gen_version_relp 


gen_version_name_length 


access_name_relp 


access_name_length 


comment_relp 


comment_length 


text_boundary 


Stat_boundary 


source_map_relp 


area_relp 


1s a code designating the version of the generator 
that created this object segment. A generator's 
version number is normally changed when the 
generator or its output is Significantly modified. 


is a calendar clock reading specifying the date and 
time when this generator was created. 


is a calendar clock reading specifying the date and 
time when this symbol block was generated. 


is the name of the processor that generated this 
symbol block. 


is an offset (relative to the base of the symbol 
block) to an aligned String describing the version 
of the generator. For example: 


"PL/I Compiler Version 7.3 
of Wednesday, July 28, 1971" 


The integer part of the version number embedded in 
the string must be identical to the number stored 
in gen_version_number. 


is the length of the aligned String describing the 
version of the generator. 


is an offset (relative to the base of the symbol 
block) to an aligned string containing the access 
identification (i.e., the value returned by the 
get_group_id_ Subroutine described in the MPM 
Subroutines) of the user for whom this symbol block 
was created. 


is the length of the aligned string containing the 
access identification of the user for whom the 
Symbol block was created. 


is an offset (relative to the base of the symbol 
block) to an aligned string containing 
generator-dependent symbolic information. For 
example, a compiler might store diagnostic messages 
concerning nonfatal errors encountered while 
generating the object segment. A value of "0O"b 
indicates no comment. 


is the length of the aligned string containing 
generator-dependent symbolic information. 


is a number indicating the boundary on which the 
text section must begin. For example, a value of 
32 would indicate that the text section must begin 
on aO mod 32 word boundary. This value must be a 
multiple of 2. It is used by the binder to 
determine where to locate the text section of this 
object segment. | 


is the same as text_boundary except that it applies 
to the internal static area of the linkage section 
of this object segment. 


is an offset (relative to the base of the symbol 
block) to the source map (see "Source Map" below). 


is an offset (relative to the base of the symbol 
block) to the variable-length area of the symbol 
block. The contents of this area depend on the 
Symbol block. 
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section_relp 


18. block_size 

19. next_block_thread 

20. text_relocation_relp 
21. def_relocation_relp 
22. link_relocation_relp 
23. symbol_relocation_relp 
24. default_truncate 

25. optional_truncate 


source Map 


is an offset (relative to base of the symbol block) 
to the base of the symbol section; that is, the 
negative of the offset of the symbol block in the 
Symbol section. 


is the size of the symbol block (including the 
header) in words. 


is a thread (relative to the base of the symbol 
section) to the next symbol block. This item is 
"O"b for the last block. 


is an offset (relative to the base of the symbol 
block) to text section relocation information (see 
"Relocation Information" below). 


is an offset (relative to the base of the symbol 


block) to definition section relocation 


information. 


is an offset (relative to the base of the symbol 
block) to linkage section relocation information. 


is an offset (relative to the base of the symbol 
block) to symbol section relocation information. 


is an offset (relative to the base of the symbol 
block) starting from which the binder 
Systematically truncates control information (such 
aS relocation bits) from the symbol section, while 
Still maintaining such information as the symbol 
tree. 


is an offset (relative to this base of the symbol 
block) starting from which the binder’ can 
optionally truncate nonessential parts of the 
symbol tree in order to achieve maximum reduction 
in the size of a bound object segment. 


The source map is a structure that uniquely identifies the source segments 
used to generate the object segment. It has the following format: 


del 1 source_map 

2 decl_vers 

2 size 

2 map (size) 
3 pathname_relp 
3 pathname_length 
3 uid 
3 dtm 


where: =. 


1. 
rae 


decl_vers 


size 


aligned, 

fixed bin initial(1), 
fixed bin, 

aligned, 

bit(18) unaligned, 
bit(18) unaligned, 
bit(36) aligned, 
fixed bin(71); 


is the version number of the structure. 
is the number of entries in the map array; that is, 


the number of source segments used to generate this 
object segment. 
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3% pathname_relp is an offset (relative to the base of the symbol 
block) to an aligned string containing the absolute 
pathname of this source segment. 


4, pathname_length is the length of the above string. 


oe uid is the unique identifier of this source segment at 
the time the object segment was generated. 


6. dtm is the date-time-modified value of this source 
segment at the time the object segment was created. 


Relocation Information 


Relocation information, designating all instances of relative addressing 
Within a given section of the object segment, enables the relocation of the 
section (as in the case of binding). A variable-length prefix coding scheme is 
used, where there is a logical relocation item for each halfword of ae given 
section. If the halfword is an absolute value (nonrelocatable), that item is a 
Single bit whose value is 0. Otherwise, the item is a string of either 5 or 15 
bits whose first bit is set to "1"b. The relocation information is concatenated 
to form a single string that can only be accessed sequentially. If the next bit 
is a zero, it is a single-bit absolute relocation item; otherwise, it is either 
a 5- or a 15-bit item depending upon the relocation codes defined below. 


There are four distinct blocks of relocation information, one for: each of 
the four object segment sections: text, definition, linkage and symbol; these 
relocation blocks are known as rel_text, rel_def, rel_link and rel_symbol, 
respectively. 


The relocation blocks reside within the Symbol block of the generator that 
produced the object segment. The correspondence between the packed relocation 
items and the halfwords in a given section is determined by matching the 
Sequence of items with a sequence of halfwords, from left-to-right and from 
word-to-word by increasing value of address. 


The relocation block pointed to from the Symbol block header (e.g., 
rel_text) is structured as follows: 


del 1 relinfo aligned, 

2 decl_vers fixed bin initial(2), 

2 n_bits fixed bin, 

2 relbits bit(O refer(n_bits)) aligned; 
where: 
Is decl_vers is the version number of the structure. 
2. n_bits is the length (in bits) of the string of relocation 

bits. 

cr relbits is the string of relocation bits. 
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relocation types, 


Following is a tabulation of the possible codes and their corresponding 


"OND = 
"170000"b - 
"170001"b - 
"10010"b - 
"10011"b - 
"10100"b - 
"10101"b - 
"170110"b = 
"10111"b = 
"11000"b - 
"11001"b = 
"171010"b -= 
"11011"b = 
"71100"b - 
"11101"b = 
"11110"b - 
"11111"b = 


absolute 
text 


negative text 


link 18 


negative link 18 


link 15 


definition 


symbol 
negative symbol 


internal storage 18 


internal storage 15 


self relative 


followed by a description of each relocation type. 


absolute 


text 


negative text 

link 18 

negative link 18 ee 
link 15 | 
definition 

symbol 

negative symbol 

internal storage 18 

internal storage 15 

self relative 

unused 

unused 

unused 

expanded absolute 

escape 


does not relocate. 
uses text section relocation counter. 


us2s text section relocation counter. The reason 
for having distinct relocation codes for negative 
quantities is that special coding might be 
necessary to convert the 18-bit field in question 
into its correct fixed binary form. 


uses linkage section relocation counter on the 
entire 18-bit halfword.. This, as well as the 
negative link 18 and the link 15 relocation codes 
apply only to the array of links in the linkage 
section (i.e., by definition, usage of these 
aaa codes implies external reference through 
a link). 


is the same as link 18 above. 
uses linkage section relocation counter on the 
low-order 15 bits of the halfword. This relocation 


code can only be used in conjunction with an 
instruction featuring a base/offset address field. 


indicates that the halfword contains an address 
that is relative to the base of the definition 
section. 

uses symbol section relocation counter. 


is the same as symbol above. 


uses internal storage relocation counter on the 
entire 18-bit halfword. 


uses internal storage relocation counter on the 
low-order 15 bits of the halfword. 


indicates that the halfword contains a relocatable 


address that is referenc2d using a location counter 
modifier; the instruction is self-relocating. 
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13. expanded absolute allows the definition of a block of absolute 
relocated halfwords, for efficiency reasons. It 
has been established that a major part of an object 
program has the absolute relocation code. The five 
bits of relocation code are immediately followed by 
a fixed length 10-bit field that is a count of the 
number of contiguous halfwords all having an 
absolute relocation. Use of the expanded absolute 
code can be economically justified only if the 
number of contiguous absolute halfwords exceeds 15. 


14. escape reserved for possible future use. 


STRUCTURE OF THE OBJECT MAP 


The object map contains information used to locate the various sections of 
an object segment. The map itself can be located immediately before or 
immediately after any one of the five sections. Translators normally place it 
immediately after the symbol section. The last word of the object segment (as 
defined by the bit count of the object segment) must contain a left-justified 
18-bit offset (relative to the base of the object segment) to the object map. 
The object map has the following format: 


del 1 object_map aligned, 
2 decl_vers fixed bin init(2), 
2 identifier char(8) aligned, 
2 text_relp bit(18) unaligned, 
2 text_length bit(18) unaligned, 
2 def_relp bit(18) unaligned, 
2 def_length ' bit(1&) unaligned, 
2 link_relp bit(18) unaligned, 
2 link_length bit(18) unaligned, 
2 static_relp bit(18) unaligned, 
2 static_length bit( 15) unaligned, 
2 symb_relp bit(18) unaligned, 
2 symb_length bit(18) unaligned, 
2 bmap_relp bit(18) unaligned, 
2 bmap_length bit(18) unaligned, 
2 entry_bound bit(18) unaligned, 
2 text_link_relp bit(18) unaligned, 
2 format aligned, 
3 bound bit(1) unaligned, 
3 relocatable bit(1) unaligned, 
3 procedure bit(1) unaligned, 
3 standard bit(1) unaligned, 
3 separate_static bit(1) unaligned, 
3 links_in_text bit(1) unaligned, 
3 unused bit(30) unaligned; 
where: 
1. decl_vers is the version number of the structure. 
2. identifier is the constant "obj_map". 
3. text_relp is an offset (relative to the base of the object segment) 
to the base of the text section. 
4, text_length is the length (in words) of the text section. 
5. def_relp is an offset (relative to the base of the object segment) 


to the base of the definition section. 
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ws 


14. 
15 <« 


16. 


17. 


18. 


19. 


20. 


21. 


22. 


23. 


def_length 


link_relp 


link_length 


Sstatic_relp 


static_length 


symb_relp 


symb_length 
bmap_relp 


bmap_length 


entry_bound 
text_link_relp 


bound 


relocatable 


procedure 


Standard 


separate_static 


links_in_ text 


unused 


is the length (in words) of the definition section. 


is an offset (relative to the base of the object segment) 
to the base of the linkage section. 

is the length (in words) of the linkage section. 

is an offset (relative to the base of the object segment) 
to the base of the static section. 

is the length (in words) of the static section. 

is an offset (relative to the base of the object segment) 
to the base of the symbol section. 

is the length (in words) of the symbol section. 

is an offset (relative to the base of the object segment) 


to the base of the break map section. 


is the length (in words) of the break map section. 


is the offset of the end 
the object segment is to 


of the entry transfer 
be a gate. 


vector if 


is the offset of the 
links_in_text equals sd lia © a 


first text-embedded link if 


indicates if the object segment is a bound segment. 
STD the object segment is a bound segment 
"O"b the object segment is not a bound segment 


indicates if the object segment is relocatable; that is, 
if it contains relocation information. This information 
(if present) must be stored in the segment's first symbol 
block. See "Structure of the Symbol Section" above. 7 

a 9 the object segment is relocatable 

"Ob the object segment is not relocatable 


indicates whether this is an executable object segment. 
si lB 8 this is an executable object segment 


"O"b this is not an executable object segment 

indicates whether the object segment is in standard format. 

ws 8 the object segment is in standard format 

"O"b the object segment is not in standard format 

indicates whether the static section is separate from the 

linkage section. | 

TD the static section is separate from the linkage 
section 

"Ob the static section is not separate from the linkage 
section 


indicates whether the object segment contains text-embedded 


links. 

al (eu @ the object segment contains text-embedded links 

"Ob the object segment does not contain text-embedded 
links 


is reserved for future use and must be "O"b, 
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GENERATED CODE CONVENTIONS 


The 


following discussion specifies those portions of generated code that 


must conform to a system-wide standard. For a description of the various 
relocation codes see "Structure of the Symbol Section" above. 


Text Section 


Those parts of the text section that must conform to a system-wide standard 


are: 


entry sequence 
text relocation codes. 


ENTRY SEQUENCE 


The entry sequence must fulfill two requirements: 


The location preceding the entry point (i.e., entry point minus 1) 
must contain a left adjusted 18-bit relative pointer to the definition 
of that entry point within the definition section 


The entry sequence executed within that entry point must store an ITS 
pointer to that entry point in the entry_ptr field in the stack frame 
header (as described in the stack frame include file). The 
procedure's current stack frame can then be used to determine the 
address of the entry point at which it was invoked. That entry's 
Symbolic name can be reconstructed through use of its definition 
pointer. (See "Entry Sequence" earlier in this section.) 


TEXT RELOCATION CODES 


The following list defines those relocation codes that can be generated in 
conjunction with the text section. These can be generated only within the scope 
of the restrictions specified. 7 


absolute no restriction 

text no restriction 

negative text no restriction 

link 18 can only be a direct (i.e., unindexed) reference to 
a link. 

link 15 can only appear within the address field of a 
pointer-register/offset type instruction 
(bit 29 = "1"b). The first two bits of the modifier 


field of the instruction cannot be "10"b. If - the 
instruction uses indexing, the first two bits of the 
modifier must be i fie (aks oes Also the following 
instruction codes cannot have this relocation code: 


STBA (551)8 
STBQ (552)8 
STCA (751)8 
STCQ (752)8 
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SY 


definition the offset to be relocated must be that of the 
beginning of a definition (relative to the beginning 
of the definition section). 


symbol no restriction 
internal storage 18 no restriction 
internal storage 15 can only apply to the left half of a word. If the 


word is an instruction, the first two bits of the 
modifier must not be "10"b. 


self relative no restriction 
expanded absolute no restriction. 
The restrictions imposed upon the link 15 and internal storage 15 


relocation codes stem from the fact that these relocation codes apply to 
pointer-register/offset type address fields encountered in the address portion 


of machine instructions. Since the effective value of such an address is 
computed by the hardware at execution time, certain hardware restrictions are 
imposed on instructions containing them. When the Multics binder processes 


these instructions, it often resolves them into simple-address format and has to 
further modify information in the opcode (right-hand) portion of the instruction 
word. Therefore, these relocation codes must only be specified in a context 
that is comprehensible to the Multics processor. 


Definition Section | 


Those parts of the definition section that must conform to a system-wide 
standard are: 


general structure 
definition relocation codes 
implicit definitions 


DEFINITION RELOCATION CODES 


absolute 7 no restriction 
text no restriction 
link 18 no restriction 
definition no restriction 
symbol no restriction 
internal storage 18 no restriction 
self relative no restriction 
expanded absolute no restriction 
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IMPLICIT DEFINITIONS 


All generated object segments must feature the following implicit 
definition: 


symbol_table defines the base of the symbol block generated by the 
current language processor, relative to the base of the 
symbol section. 


Linkage Section 


Those parts of the linkage section that must conform to a system-wide 
Standard are: 


internal storage 
links 
linkage relocation codes 


INTERNAL STORAGE 


The internal storage is a repository for items of the internal static 
Storage class. It may contain data items only; it cannot contain any executable 
code. 


LINKS 


The link area can only contain a set of links. The links must be 
considered as distinct unrelated items, and no structure (e.g., array) of links 
can be assumed. They must be accessed explicitly and individually through an 
unindexed internal reference featuring the link 18 or the link 15 relocation 
codes. The order of links will not necessarily be preserved by the binder. 


LINKAGE RELOCATION CODES 


Only the linkage section header and the links can have relocation codes 
associated with them (the internal storage area has associated with it a single 
expanded absolute relocation item). They are: 


absolute | no restriction; mandatory for the internal storage 
area 
text no restriction 
link 18 no restriction 
negative link 18 no restriction 
definition no restriction 
internal storage 18 no restriction 
expanded absolute no restriction 
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Static section 


The static section does not have relocation codes associated with it. 
Absolute relocation is assumed. See "Internal Storage Area" above. 


Symbol Section 


The symbol section can contain information related to some other section 
(such as a symbol tree defining addresses of symbolic items), and therefore can 
have relocation codes associated with it. They are: 


absolute no restriction 
text no restriction 
link 18 no restriction 
definition no restriction 
symbol | no restriction 
negative symbol no restriction 
internal storage 18 no restriction 
self relative no restriction | 
expanded absolute no restriction 


STRUCTURE OF BOUND SEGMENTS 


A bound segment consists of several object segments that have been combined 
so that all internal intersegment references are automatically prelinked and to 
reduce the combined size by minimizing page breakage. The component segments 
are not simply concatenated; the binder breaks them apart and creates an object 
segment with single text, definition, static, linkage, and symbol sections as 
illustrated in Figure 1-3 below. (When the static section is separate, it is 
located before the linkage header rather than between the linkage header and the 
links. ) As explained below, the definition section and link array are 
completely reconstructed while the text, internal static, and symbol sections 
are the corresponding concatenations of the component segments' text, internal 
static, and symbol sections with relocation adjustments. (See "Structure of 
the Symbol Section" above.) If all of the components' static sections are 
separate (i.e., not in linkage), the bound segment has a _ separate static 
section; otherwise, all component static sections are placed in the bound 
segment's linkage section. 
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text for component 1 

text for component 2 
text section | ; 

text for component n 


definition section 


linkage header 
int. static for component 1 
int. static for component 2 


linkage section ; 


int. static for component n 


links 


first reference trap 
symbol block for binder 
symbol section symbol block for component 1 


symbol block for component n 


object map 


Figure 1-3. Structure of a Bound Segment 
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Internal Link Re 1 


The primary distinction between bound and unbound groups of segments occurs 
in the manner in which they reference external items and are themselves 
referenced. Most references by one component to another component in the same 
bound segment are prelinked; i.e., the link references are converted to direct 
text-to-text references and the associated links are not regenerated. The 
remaining external links are combined so that for the whole bound segment there 
is only one link for each different target. Prelinking enables some component 
segments to lose their identity in cases where the bound segment itself is the 
main logical entity, having been coded as separate segments for ease of coding 
and debugging. Definitions for external entries that are no longer necessary, 
i.e., have become completely internal, can be omitted from the bound segment 
(see the bind command described in MPM Commands). 


Definition Section 


The definition section of a bound segment is generally more elaborate than 
that of an unbound object segment because it reflects both the combination and 
deletion of definitions. There is a definition block for each component. It 
contains the retained definitions and the segment names associated with the 
component. This organization allows definitions for multiple entries with the 
same name to be distinguished. The first definition block is for the binder and 
contains a definition for bind_map, discussed below. 


The symbol block of the binder has a standard header if all of the 
components are standard object segments. The symbol block can be located using 
the bind_map definition. Most of the items in the header are adequately 
explained under "Structure of the Symbol Section" above; however, some have 
special meaning for bound segments. The format of a standard symbol block 
header is repeated below for reference, followed by the explanations specific to 
the binder's symbol block. 


del 1 symbol_block_header aligned, 

| 2 decl_vers fixed bin initial(1), 
2 identifier char(8) aligned, 
2 gen_version_number fixed bin, 
2 gen_creation_time fixed bin(71), 
2 object_creation_time fixed bin(71), 
2 generator char(8) aligned, 
2 gen_version_name_relp bit(18) unaligned, 
2 gen_version_name_length bit(18) unaligned, 
2 access_name_relp bit(18) unaligned, 
2 access_name_length bit(18) unaligned, 
2 comment_relp bit(18) unaligned, 
2 comment_length bit(18) unaligned, 
2 text_boundary bit(18) unaligned, 
2 stat_boundary bit(18) unaligned, 
2 source_map_relp bit(18) unaligned, 
2 area_relp bit(18) unaligned, 
2 section_relp bit(18) unaligned, 
2 block_size bit(18) unaligned, 


2/77 1-29 | AK92B 


2 next_block_thread bit(18) unaligned, 
e text_relocation_relp bit(18) unaligned, 
e def_relocation_relp bit(18) unaligned, 
2 link_relocation_relp bit(18) unaligned, 
2 symbol_relocation_relp bit(18) unaligned, 
2 default_truncate bit(18) unaligned, 
2 optional _truncate bit(18) unaligned; 
where: 
2. identifier is the string "bind_map". 
6. generator is the string "binder", 


11. comment_relp is always "0O"b, 


16. area_relp is an offset (relative to the base of the symbol block) to 
the beginning of the bind map. (See "Bind Map" below.) 


Bound segments currently -are not relocatable, so none of the relocation 
relative pointers or truncation offsets have any meaning. 


Bind Map 


The bind map is part of the symbol block produced by the binder and 
describes the relocation values assigned to'the various sections of the bound 
component object segments. It consists of a variable length structure followed 
by an area in which variable length symbolic information is stored. The bind 
map structure has the following format: 


del 1 bindmap based aligned, 

2 decl_vers fixed bin initial(1), 

2 n_components fixed bin, 

2 component(0 refer(n_components)) aligned, 
3 name_relp bit(18)unaligned, 
3 name_length bit(18) unaligned, 
3 generator_name char(8) aligned, 
3 text_relp bit(18) unaligned, 
3 text_length bit(18) unaligned, 
3 static_relp bit(18) unaligned, 
3 static_length bit(18) unaligned, 
3 symbol_relp bit(18) unaligned, 
3 symbol_length bit(18) unaligned, 
3 defblock_relp bit(18) unaligned, 
3 number_of_blocks bit(18) unaligned, 

2 bindfile_name _ aligned, 
3 bindfile_name_relp bit(18)unaligned, 
3 bindfile_name_length bit(18)unaligned, 

2 bindfile_date_updated ehar(24), 

2 bindfile_date_modified char(24); 

where: 
1. decl_vers is a constant designating the format of this 


structure; this constant is modified whenever the 
Structure is, allowing system tools to easily 
differentiate between several incompatible 
versions of a single structure. 


2. n_components is the number of component object segments bound 
within this bound segment. 
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wd 


14. 


15. 


16. 


18. 


2/TT 


component 


name_relp 


name_length 
generator_name 
text_relp 
text_length 
static_relp . 


static_length 


symbol_relp 


symbol_length 


defblock_relp 


number_of_blocks 


bindfile_name_relp 


‘bindfile_name_length 


bindfile_date_updated 


bindfile_date_modified 


is a variable-length array featuring one entry per 
bound component object segment. 


is the offset (relative to the base of the _ bind 
map structure) of the symbolic name of the bound 
component. This is the name under which the 


component object was identified within the archive 
file used as the binder's input (i.e., the name 
corresponding to the object's objectname entry in 
the bindfile). 


is the length (in characters) of the component's 
name. 

is the name of the translator that created this 
component object segment. 

is the offset (relative to the base of the bound 
segment) of the component's text section. 

is the length (in words) of the component's text 
section. 

is the offset (relative to the base of the static 
section) of the component's internal static. 

is the length of the component's internal static. 
is an offset (relative to the base of the symbol 
section) to the component's symbol section. 

is the length of the component's symbol section. 
if nonzero, this is a pointer (relative to the 


base of the definition section) to the component's 
definition block (first class-3 segname definition 
of that component's definition block). 


is the number of symbol blocks in the component's 


symbol section. 


is the offset (relative to the base of the symbol 
section) of the symbolic name of the bindfile. 


is the length (in characters) of the bindfile 
name. 
is the date, in symbolic form, that the bindfile 


was updated in the archive (of object segments) 
used as input by the binder. 


is the date, in symbolic form, that the bindfile 
was last modified before being put into the 
binder's object archive. 
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SECTION Il 


STANDARD EXECUTION ENVIRONMENT 


TANDAR CK AND K ORMAT 


Because of the linkage mechanism, stack manipulations, and the complexity 
of the Multics hardware, a series of Multics execution environment standards 
have been adopted. All standard translators (including assemblers) adhere to 
these standards as do all supervisor and standard storage system procedures. 
Furthermore, they assume that other procedures do so as well. 


Multics Stack 


The normal mode of execution in a standard Multics process uses a_=e stack 
segment. There is one stack segment for each ring. The stack for a given ring 
has the entryname stack_R, where R is the ring number, and is located in the 
process directory. Each stack contains a "header" followed by as many "stack 
frames" as are required by the executing procedures. A stack header contains 
pointers to special code and data that are initialized when the stack is 
created. Some of these pointers are variable and change during process 
execution. They are included in the stack header so that they can always be 
retrieved without supervisor intervention (for efficiency). The actual format 
of the stack header is described under "Stack Header" below. 


Stack frames begin at a location specified in the stack header, are 
variable in length, and contain both control information and data for 
dynamically active procedures. In general, a stack frame is allocated by the 
procedure to which it belongs when that procedure is invoked. The stack frames 
are threaded to each other with forward and backward pointers, making it an easy 
task to trace the stack in either direction. The stack usage described below is 
critical to normal Multics operation; any deviations from the stated discipline 
can result in unexpected behavior. 
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stack Header 


The stack header contains pointers (on a per-ring basis) to information 


about the process, to operator segments, and to code sequences that can be 


used 


to invoke the standard call, push, pop, and return functions (described below). 
Figure 2-1 gives the format of the stack header. The following descriptions are 


based on that figure and on the followgdng PL/I declaration. 


+32) 
‘Push Operator }|Return 


+0 | 
, iCombined 
| Reserved 1Old Lot iStatic 
+8 | tPointer tPointer 
! t ! i ] 
| , I 1 ' ! 
i{Combined iMax iCurrent;System Storage {User Storage 
iLinkage t{Lot t{Lot iPointer i|Pointer 
tPointer i1Size isize 
+16} 
{Null i|Stack Begin iStack End ‘Lot 
i1Pointer iPointer iPointer iPointer 
] i ' 
Sa ee LEY ANN STS eee ae eee Ne eee ee ee ee eat eee ee 
+24} 
iSignal BAR Mode (PL/I Operators |} 
iPointer Stack Pointer iPointer ! 
! | 
1 I 
i 
i!Pointer {Pointer ‘Operator Ptr 
i ] j ' j 
SEED Geeeeeeenen es er e f 
+40! 
iTranslator iInternal Static |System Condition! Unwinding 
|Operator iOffset Table iTable Pointer |Procedure 
tPointer tPointer iPoi 
+48} 
6 i 
] j 
i*system Link |} 
[Info Pointer | 
+56} Reserved 


Figure 2-1. 


del stack_header based 
pad1(4) 
old_lot_ptr 
combined_stat_ptr 
clr_ptr 
max_lot_size 

pad2 

cur_lot_size 

pad3 
system_storage_ptr 
user_storage_ptr 
null_ptr 
stack_begin_ptr 
stack_end_ptr 
lot_ptr 

Signal_ptr 
bar_mode_sp_ptr 
plil_operators_ptr 
call_op_ptr 


MM PM MMMM PP Pl PPP NPN PND lh = 
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Operator {Short Return 


Stack Header Format 


aligned, 

fixed bin, 

ptr, 

ptr, 

ptr, 

fixed bin(17) unaligned, 
bit(18) unaligned, 


fixed bin(17) unaligned, 


bit(18) unaligned, 
ptr, 
ptr, 
ptr, 
ptr, 
ptr, 
ptr, 
ptr, 


all Operator 


Entry Operator 


AK92B 
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push_op_ptr 
return_op_ptr 
short_return_op_ptr 
entry_op_ptr 
trans_op_tv_ptr 
isot_ptr 

sct_ptr 
unwinder_ptr 
sys_link_info_ptr 


MM M PM MM PM PN Po 


pad4(14) 

where: 

Ve padi 

2. old_lot_ptr 

3. combined_stat_ptr 

4, elr_optr 

5. max_lot_size 

6. pad2 

7. cur_lot_size 

8. pad3 

9. system_storage_ptr 
10. user_storage_ptr 
11. null_ptr 

12. stack_begin_ptr 
13.  stack_end_ptr 


fixed bin; 


is unused. 


is a pointer to the linkage offset table (LOT) for 
the current ring. This field is obsolete. 


| is a pointer to the area in which separate static 


sections are allocated. 


is a pointer to the area in which linkage sections 
are allocated. 


is the maximum number of words (entries) that the 
LOT and internal static offset table (ISOT) can 
have. 


is unused. 


is the current number of words (entries) in the 
LOT and ISOT. 


is unused. 


is a pointer to the area used for system storage, 
which includes command storage and the *system 
link name table. 


is a pointer to the area used for user’ storage, 
which includes FORTRAN common and PL/I external 
static variables whose names do not include "$", 


contains a null pointer value. In some 
circumstances, the stack header can be treated as 
a stack frame. When this is done, the null 


pointer field occupies the same location as the 
previous stack frame pointer of the stack frame. 
(See "Multics Stack Frame" below.) A null pointer 
indicates that there is no stack frame prior to 
the current one. 


is a pointer to the first stack frame on the 
stack. The first stack frame does not necessarily 
begin at the end of the stack header. Other 
information, such as the linkage offset table, can 
be located between the stack header and the first 
stack frame. 


is a pointer to the first unused word after the 
last stack frame. It points to the location where 
the next stack frame is placed on this stack (if 
one is needed). A stack frame must be a multiple 
of 16 words; thus, both of the above pointers 
point to O (mod 16) word boundaries. 
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14. lot ptr 


15. signal ptr 


16. bar_mode_sp_ptr 


17. pli vloperators_ptr 
18. call_op_ptr 


19. push_op_ptr | 


20. return_op_ptr 


21. short_return_op_ptr 
22. -entry_op_ptr 

23. trans_op_tv_ptr 

24. isot_ptr 


25. sct_ptr 


26. unwinder_ptr 
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is a pointer to the linkage offset table (LOT) for 
the current ring. The LOT contains packed 
pointers to the dynamic linkage sections known in 
the ring in which the LOT exists. The linkage 
offset table is described below under "Linkage 
Offset Table." 


is a pointer to the signalling procedure to be 
invoked when a condition is raised in the current 
ring. 


is a pointer to the stack frame in effect when BAR 
mode was entered. (This is needed because typical 
BAR mode programs can change the word offset of 
the stack frame pointer register. ) 


is a pointer to the standard operator segment used 
by PL/I. It is used by PL/I and FORTRAN object 
code to locate the appropriate operator segment. 


is a pointer to the Multics standard call operator 
used by ALM procedures. It is used to invoke 
another procedure in the standard way. 


is a pointer to the Multics standard push operator 
that is used by ALM programs when allocating a new 
stack frame. All push operations performed on a 
Multics stack should use either this or an 
equivalent operator; otherwise results are 
unpredictable. (The push operation was formerly 
called save.) | 


is a pointer to the Multics standard return 
operator used by ALM procedures. It assumes that 
a push has been performed by the invoking ALM 
procedure and pops’ the stack prior to returning 
control to the caller of the ALM procedure. 


is a pointer to the Multics standard short return 
operator used by ALM procedures. It is invoked by 
a procedure that has not performed a push to 
return control to its caller. 


is a pointer to the Multics' standard entry 
operator. The entry operator does little more 
than find a pointer to the invoker's' linkage 
section. 


points to a vector of pointers to special language 
Operators; this table can be expanded to 
accommodate new languages without causing a change 
in the stack header. 


is a pointer to the internal static offset table 
(ISOT). The ISOT contains packed pointers to the 
dynamic internal static sections known in the ring 
in which the ISOT exists. 


is a pointer to the system condition table (SCT) 
used by system code in handling certain events. 


is a pointer to the unwinding procedure to be 


invoked when a nonlocal goto is executed in the 
current ring. 
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e7. sys_link_info_ptr is a pointer to the *system link name table. 


28. pad4 is unused. 


The call, push, return, short return, and entry operators are invoked by 
the object code generated by the ALM assembler. Other translators that intend 
to use the standard call/push/return strategy should either use these operators 
or an operator segment with a set of operators consistent with these. For a 
detailed description of what the operators do and how to invoke them, see 
"Subroutine Calling Sequences" later in this section. 


The PL/I and FORTRAN compilers use slightly different operators that 
perform equivalent and compatible functions. All supported translators, 
however, depend on the effects generated by these operators. 


ultic tac r 


The format given below for a standard Multics stack frame must be strictly 
followed because several critical procedures of the Multics system depend on it. 
A bad stack segment or stack frame can easily lead to process termination, 
looping, and other undesirable effects. 


In the discussion that follows, the "“owner" of a stack frame is the 
procedure that created it (with a push operation). Some programs (generally ALM 
programs) never perform a push and hence do hot own a= stack frame. If a 
procedure that does not own a stack frame is executing, it can neither call 
another procedure nor use stack temporaries; all stack information refers to the 
program that called such a program. | 


Figure 2-2 illustrates the detailed structure of a stack frame. The 
following descriptions are based on that diagram and on the following PL/I 
declaration. 
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stack_frame +0} 


Pointer Register Storage 


+16} 
‘Previous Stack}]Next Stack 
‘Frame Pointer ‘iFrame Pointer 
i 


Return 
Pointer 


1 
1 
Entry 
Pointer 

| 


+24 

|Operator | Argument tInternal{ ** (On Unit |Operator | 

iLinkage | Pointer Static | ‘Relative; Return | 

iPointer ‘Pointer | ‘Pointer | Offset | 

t | t | i ! 

eee eee ee! Ae et eee REE AOE EAS See ee RS SAE, Ce eee 
+32; 


Register Storage 


+40 


Temporaries 


*## Reserved 
Figure 2-2. Stack Frame Format 
del 1 stack_frame based (sp) aligned, 
2 prs(16) fixed bin, 
2 prev_stack_frame_ptr ptr, 
2 next_stack_frame_ptr ptr, 
2 return_ptr ptr, 
2 entry_ptr ptr, 
2 operator_link_ptr ptr, 
2 argument_ptr ptr, 
2 static_ptr ptr unaligned, 
2 reserved fixed bin, 
2 on_unit_rel_ptrs(2) bit(18) unaligned, 
2 translator_id bit(18) unaligned, 
2 operator_return_offset bit(18) unaligned, 
2 regs(8) fixed bin; 
where: 
1. prs is used to save pointer registers of the calling 
program when the ALM call operator is invoked. 
2. prev_stack_frame_ptr is a pointer to the base of the stack frame of the 
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procedure that called the procedure owning the 
current stack frame. This pointer may or may not 
point to a stack frame in the same stack segment. 
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3. 


11. 


12. 


13. 
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next_stack_frame_ptr 


return_ptr 


entry_ptr 


operator_link_ptr 


argument_ptr 
static_ptr 


reserved 


on_unit_rel_ptrs 


translator_id 


operator_return_offset 


regs 


is a pointer to the base of the next stack frame. 
For the last stack frame on a stack, the pointer 
points to the next available area in the stack 
where a procedure can lay down a stack frame; 
i.e., it has the same value as the stack_end_ptr 
in the stack header. The previous stack frame 
pointers and the next stack frame pointers form 
threads through all active frames on the stack. 
These two threads are used by debugging tools to 
search and trace the stack as well as by the 
call/push/return mechanism. 


is a pointer to the location to which a return can 
be made in the procedure that owns the. given 
frame. This pointer is undefined if the procedure 
has never made an external call, and points to the 
return location associated with the last external 
call if the given procedure has been returned to 


. and is currently executing. 


is a pointer to the procedure entry point that was 
called and that owns the stack frame. The pointer 
points to a standard entry point. See "Structure 
of the Text Section" in Section I. 


is usually the operator pointer being used by the 
procedure that owns the given stack frame. For 
ALM programs, this points to the linkage section 
of the procedure. 


is a pointer to the argument list passed to the 
procedure that owns the given stack frame. 


is a pointer to the internal static storage for 
the procedure owning the stack frame. 


is reserved for future use. 


is a pair of relative pointers to on unit 
information contained within the stack frame. 
This on unit information is valid only if bit 29 
of the second word of prev_stack_frame_ptr is a 1. 
(This bit is automatically set to O when a push is 
performed by the procedure that owns the stack 
frame.) The first of the on_unit_rel_ptrs is a 
pointer (relative to the stack frame base) toa 
list of enabled conditions. The second of the 
on_unit_rel_ptrs is obsolete. 


is a coded number indicating the translator’ used 
to generate the object code of the owner of the 
stack frame. 


contains a return location for certain 
plil_operators_ functions. If it is nonzero, it is 
a relative pointer to the return location in the 
compiled program (return from pli_operators_). If 
it is zero, a dedicated register (known by 
plil_operators_) contains the return location. 


is used to save arithmetic registers of the 


calling program when the ALM call operator is 
invoked. 
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Two major areas of a stack frame not explicitly defined above are the first 
16 words and words 32 through 39. The contents of these areas is not always 
defined or meaningful, although they have a well-defined purpose for ALM 
programs and are used internally by the PL/I and FORTRAN programs. The 
procedure owning the stack frame can use these areas as it sees fit. 


Linkage Offset Table 


As described above, each stack header contains a pointer to the linkage 
offset table (LOT) for the current ring. The LOT is an array, indexed by text 
segment number, of packed pointers to the linkage sections for the procedure 
segments known in the current ring. 


The structure of the LOT is defined by the following PL/I declaration: 


del 1 lot based (lot_ptr) aligned, 
2 linkage_ptr (0: stack_header.cur_lot_size-1) ptr unaligned; 


where linkage_ptr is the array of linkage section pointers. 


If one of the slots in the linkage_ptr array contains all O's, the segment 
number associated with the slot either does not correspond to a known segment or 
corresponds to a segment that does not have a linkage section allocated. 


The stack header in each ring contains a pointer to the internal static 
offset table (ISOT) for the current ring. The ISOT is an array, indexed by text 
segment number, of packed pointers to the internal static sections for the 
corresponding procedure segments known in the current ring. Since the ISOT 
always immediately follows the LOT, the isot_ptr is redundant but is retained 
for efficiency. 


‘The internal static pointers are identical to the linkage section pointers 
unless the corresponding object segment was generated with separate static. if 
the static is separate, i.e., not allocated in the linkage section, the internal 
static pointer either points to the allocated static or contains a value that 
causes an "jsot fault" if referenced. 


The structure of the ISOT is defined by the following PL/I declaration: 


del 1 isot based (isot_ptr) aligned, 
2 static_ptr (0: stack_header.cur_lot_size-1) ptr unaligned; 


where static_ptr is the array of static/linkage section pointers. 
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SUBROUTINE CALLING SEQUENCES 


The Multics standard call and return conventions are described in the 
following paragraphs. For information about the format of stack segments and 
stack frames, see "Standard Stack and Linkage Area Formats" above. 


The call and return from one procedure to another can be broken down into 
seven separate steps. Operators to perform these steps have been provided in 
the standard operator segment named pli_operators_ (for PL/I, FORTRAN, and ALM 
procedures). These operators are invoked when appropriate by the object code 
generated by these translators. 


The steps involved in a call and return and the associated operators are 
listed below. | 


1. A procedure call, ae a transfer of control and passing of an 
argument list pointer to the called procedure (call). 


2. Generation of a linkage (and internal static) pointer for the called 
procedure (entry). 


3. Creation of a stack frame for the called procedure (push). 


4. Storage of standard items_to be saved in the stack frame of the called 
procedure (entry and push). 


De Release of the stack frame of the ¢alled procedure just prior to 
returning (return). 


6. Reestablishment of the execution environment of the calling procedure 
(return and short_return). 


ts Return of control to the calling procedure (return and short_return). 


Preparation of the argument list, although necessary, was not listed above 
because the operators need know nothing about the format of an argument list. 
See "Argument List Format" later in this section. | 


‘The following description is based on the operators used by ALM procedures. 
The operators used by PL/I and FORTRAN procedures are basically the same but 
differ at a detailed level due to: (1) slight changes in the execution 
environment when PL/I and FORTRAN programs are running; and (2) simplification 
and combination of operators made possible by the execution environment of PL/I. 
The PL/I and FORTRAN operators are not described here other than to define a 
minimum execution environment that must be established when returning to a PL/I 
or FORTRAN program. 


(The following description is given in terms of Honeywell hardware. ) 
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Call Operator 


The call operator transfers control to the called procedure. This operator 
is invoked in two ways from ALM procedures. The first is a result of the call 
pseudo-op, which invokes the call operator after saving the machine registers in 
the calling program's stack frame and loading pointer register 0 with a pointer 
to the argument list to be passed to the called procedure. Upon return to the 
calling program, these saved values are restored into the hardware registers by 
the calling procedure. The second way that ALM procedures can invoke the call 
operator is through the’ short_call pseudo-op. This is used when the calling 
procedure does not need all of the machine registers saved and restored across 
the call. The ALM procedure can selectively save whatever registers are needed. 


Neither the call nor the short_call pseudo-ops (nor the PL/I and FORTRAN 
equivalents) require or expect the machine registers to be restored by the 
called procedure. In fact, only the pointer registers 0 (operator segment 
pointer) and 6 (stack frame pointer) are ever guaranteed to be restored across a 
call. It is up to the calling procedure to save and restore any other machine 
registers that are needed. 


Entry Operator 


The entry operator used by ALM programs performs two functions. It 
generates a pointer to the linkage section of the called procedure (which it 
leaves in pointer register 4) and it stores a pointer to the entry in what will 
be the stack frame of the called procedure (if' the procedure ever creates a 
stack frame for itself). At the time the entry operator is invoked, a new stack 
frame has not yet been established. Indeed, the called procedure may never 
create one. However, it is certainly possible to know where the stack frame 
will go if and when it is created and this knowledge is used to store the entry 
pointer. 


The entry operator is invoked by an ALM procedure that transfers to a label 
in another procedure that has been declared as an entry through the entry 
pseudo-op. The transfer is made to ae standard entry structure the first 
executable word of which is (PR7 is assumed to point to the base of the current 
stack segment): 


tsp2 7ientry_op,* 


The operator returns to the instruction after the tsp2 instruction, which 
may or may not be another transfer instruction. (A link to the entry, when 
snapped, points to the tsp2 instruction.) See "Structure of the Text Section" 
in Section lI. 


Some ALM programs may not require a linkage pointer. Such programs can 
declare the label to which control should be transferred with a segdef 
pseudo-op. This causes the appropriate definition and linkage information to be 
generated so that other procedures can find the entry point. When called, the 
transfer is straight to the code at the label and the normal entry structure is 
not generated or used. No linkage pointer is found and no entry pointer is 
saved. This technique is recommended only where speed of execution is of utmost 
importance since it avoids calculation of useful diagnostic information. 
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Push Operator 


The push operator used by ALM procedures is invoked as a result of the push 
pseudo-op that is used to create a stack frame for the called procedure. In 
addition to creating a stack frame, several pointers are saved in the new stack 
frame. They are: 


1 Argument pointer 

2. Linkage pointer (and internal static pointer) 
3% Previous stack frame pointer 

mM 


A Next stack frame pointer 


If the called procedure is defined as an entry (rather than segdef), the entry 
pointer has already been saved in the new stack frame. 


The push pseudo-op must be invoked if the called procedure makes further 
calls itself or uses temporary storage. Due to their manner of execution, PL/I 
and FORTRAN procedures combine the entry and push operators into a single 
operator. 


The push operator and the return operators are managers of the stack frames 
and the stack segment in general. The push operator establishes the forward and 
backward stack frame threads and updates the stack end pointer in the stack 
header appropriately. The return operators use these threads and also update 
the stack end pointer as needed. Any program that wishes to duplicate these 
functions must do so in a way that is compatible with the procedures outlined in 
this discussion and those described above under the heading "Standard Stack and 
Linkage Area Formats". 


rn r r 


‘The return operator is invoked by ALM procedures that have specified the . 
return pseudo-op. The return operator pops the stack, reestablishes the minimum 
execution environment, and returns control to the calling procedure. The only 
registers restored are pointer registers 0 and 6, as mentioned above. 


rt Return r 


The short_return operator is invoked by ALM procedures that have specified 
the short_return pseudo-op. The short_return operator differs from the return 
operator in that the stack frame is not popped. This return is used by ALM 
procedures that did not perform a push. 


2-11 | AK92 


Pseudo=-op Code Sequences 


The following code sequences are generated by the assembler for the 
specified pseudo-op. 


OBJECT CODE OPERATORS 
call: 
spri 610 
sreg 132 
epp0d arglist 
epp2 entrypoint 
tsp4 Ti} call_op, * | 
spri4 ireturn_ptr 
sti ireturn_ptr+1 
epp4 i:lp_ptr, * 
call6 10 
lpri 6,0 
lreg 6; 32 
short_call: 
epp2 entrypoint 
tsp4 7Ticall_op,* 
(as above) 
epp4 spilp_ptr, * 
return: 
tra Tireturn_op, * 
spri6 Tistack_end_ptr 
epp6 6!prev_sp, * 
epbp7 6;0 7 
epp0 O;op_ptr, * 
ldi 6;return_ptr+1 
rtcd 6ireturn_ptr 
short_return: 
tra 7ishort_return_op, * 
epbp7 6; 0 
eppO 6iop_ptr, * 
ldi 6ireturn_ptr+1 
rted 6/return_ptr 
entry: 
tsp2 Tientry_op, * 
: epp2 24-1 
epp4 Tistack_end_ptr, * 
spri2 4Yientry_ptr 
epaq 210 
lprp5 Tiisot_ptr, *au 
sprp5 4Histatic_ptr 
lprp4 Tilot_ptr, *au 
tra 2i1 
tra executable_code 
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push: 


eax] stack_frame_size 

tsp2 7ipush_op, #* 
spri2 7istack_end_ptr, * 
epp2 7istack_end_ptr, * 
spri6 2iprev_sp 
spri0 2iarg_ptr 
spri4 2ilp_ptr 
epp6 210 
eppe 610,7 
spri2 7istack_end_ptr 
spri2 6inext_sp 
eax7 1 
stx7 6;translator_id 
tra 6,0,* 


Register Usage Conventions 


The following conventions, used in the standard environment, should be 
followed by any user-written translator. 


is The only registers that are restored across a call are the pointer 
registers: 


O (ap) operator segment pointer 
6 (sp) stack frame pointer 


The operator segment pointer is restored correctly only if it is saved 
at some time prior to the call (e.g., at entry time). 


oi The code generated by the ALM assembler assumes that pointer register 

(lp) always points to the linkage section for the executing 

procedure and that pointer register 7(sb) always points to the stack 
header. 


Ss Pointer register 7 is assumed to be pointing to the base of the’ stack 
when control is passed to a called procedure. 


Argument List Format 


When a Standard call is performed, the argument pointer (pointer 
register 0) is set to point at the argument list to be used by the called 
procedure. The argument list is a sequence of pointers and control information 
about the arguments. The argument list header contains a count of the number of 
arguments, a count of the number of descriptors, and a code specifying whether 
the -argument list contains an extra stack frame pointer. The format of the 
argument list is shown in Figure 2-3. 


The argument list must begin on an even word boundary. The pointers in the 
argument list need not be ITS pointers; however, they must be pointers’ through 
which the hardware can perform indirect addressing. Packed (unaligned) pointers 
cannot be used. 
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arg count 


t 
| 
I 
1 {| dese_count 
| 


| 
( 
2 ! Pointer to argument 1 
| 
! 
( 


t 
I 
4 {| Pointer to argument 2 
' 
1 


<a 
| 


2*n Pointer to argument n 


cr 


L 


Optional pointer to stack frame 
of containing block 


Pointer to descriptor 1 


Poister to descriptor 2 


Pointer to descriptor yn 
Figure 2-3. Standard Argument List 


where: 
n is the number of arguments passed to the called procedure. 


arg count is in the left half of word 0; it is two times the number of 
arguments passed. 


code is in the right half of word 0; it is 4 for normal 
intersegment calls and 10 (octal) for calling sequences that 
contain an extra stack frame pointer. This pointer occupies 
the two words following the last argument pointer. It is 
present for calls to PL/I internal procedures and for calls 
made through PL/I entry variables. | 


desc_count is in the left half of word 1; it is two times the number of 


descriptors passed. If this number is nonzero, it must be the 
Same aS arg count. 
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An argument pointer points directl 
; y to an argument. A descript 
Points to the descriptor associated with the argument. Pee epee 


The format of an argument descriptor is described by the following PL/I 


declaration: 


del 1 descri 


—, 
OO OND FWP = 


(2 flag 
2 type 
2 packed 
2 number 
2 size 
where 
1. flag 
2% type 
3% packed 
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ptor aligned, 
bit(1), 
bit(6), 
bit(1), 


_dims bit(4), 


bit(24)) unaligned; 


always has the value "1"b and is used to tell this 
format from an earlier format. (Shown as 1 in the 
below.) 


is the data type according to the following encoding: 


real fixed binary short 

real fixed binary long 

real floating binary short 
real floating binary long 
complex fixed binary short 
complex fixed binary long 
complex floating binary ‘short 
complex floating binary long 
real fixed decimal 

real floating decimal 

11 complex fixed decimal 

12 complex floating decimal 

13 pointer 


14 offset 

15 label 

16 entry 

17 structure 
18 area 


19 bit string 
20 varying bit string 


21 character string 
22 varying character string 
23 file 


descriptor 
descriptor [ 


has the value "1"b if the data item is packed. (Shown as "p" 


in the typical descriptor below.) 
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ree 


4, 
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: tae id 
number_dims is the number of dimensions in an array. (Shown as "m" in the 


descriptor below.) The array bounds and multipliers follow the 
basic descriptors in the following manner: 


size 


see 
ct 
te 
oO 
@ 
Oo 
= 
w 
f~: 
N 
) 


lower bound 


upper bound 


multiplier 


lower bound 


upper bound 


multiplier 


If the data is packed, the multipliers give the element 
separation in bits; otherwise, they give the element separation 


in words. 


basic descriptor 


descriptive information 


for the mth 


(rightmost) dimension 


descriptive information 


for the first 


(leftmost) dimension 


is the size (in bits, characters, or words) of string or 
data, the number of structure elements for structure data, 
the scale and precision (as two 12- 
data. For arithmetic data, the 
leftmost 12 bits and the precision is recorded in the rightmost 


12 bits. The scale is a 2's complement, signed value. 


area 
or 
bit fields) for arithmetic 

scale is recorded in the 
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each 


The descriptor of a structure is i 
of its members, 
element of C or D occup 


basic descriptor of S 
basic descriptor of A 
basic descriptor of B 
lower bound of B 

upper bound of B . 
element separation of B 
basic descriptor of C 
lower bound of C 

upper bound of C 
element separation of C 
basic descriptor of D 
lower bound of D 

upper bound of D 
element separation of D 


Members of dimensioned structures are arrays, 
copies of the bounds of the containing structure. 
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and 


mmediately followed 
The example below shows a declaration 


their 


by descriptors of 
! (assuming that each 
1es one word) and its related descriptor. 


descriptor 


contains 
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SECTION III 


SUBSYSTEM PROGRAMMING ENVIRONMENT 


WRITING A PROCESS QVERSEER 


Almost every feature of. the standard Multics System interface can be 
replaced by providing a specially tailored process overseer procedure in place 


of the standard version. The standard Multics process overseer procedure, 
process_overseer_, is the initial procedure assigned to a user unless the 
project administrator specifies otherwise by an initproc or Initproc statement 
in the project. master file (PMF). (See the Multics Administrators' Manual 

i , Order No. AK51.) If a user has the V_process_overseer 


attribute, he may specify a different initial procedure when he logs in by using 
the -process_overseer (-po) control argument as in the following example: 


login Smith -po >udd>AEC>special_overseer_ 


If Smith does not have the v_process_overseer attribute, the system refuses the 
login. 


Process Initialization 


When a process is created for a user when he logs in or in response to 
either a new_proc command (described in the MPM Commands) or process termination 
Signal, the new process initializes itself, sets the default search rules, and 
then calls one of the following three procedures in the user's initial ring: 


user_real_init_admin_ for an interactive process 
absentee_real_init_admin_ for an absentee process 
daemon_real_init_admin_ for a system daemon process 


These procedures first perform several initialization tasks and then ecall 
the user's process overseer procedure, expecting that the process overseer will 
not return. A return is treated as an error, and a report is made to the system 
that the process cannot be initialized. 


In order to initialize the process, several items of information must be 
passed to the process by the system control process. The system places this 
information in a special per-process segment, called the process initialization 
table (PIT), that resides in the process directory. The user process may read 
the contents of the PIT, but may not modify it. The user_info_ subroutine 
(described in the MPM Subroutines) is used to extract information from the PIT. 
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Before calling the process overseer, user_real_init_admin_ attaches the I/O 
switch named user_i/o (through an I/O system module named in the PIT) to the 
target (also specified in the PIT). It then attaches the I/O switches named 
user_output, user_input, and error_output as synonyms of user_i/o. The I/0 
module used for an interactive process is tty_, the Multics terminal device I/O 
module. (This module is described in the MPM Subroutines. ) | 


For an absentee process, the Multics absentee I/O module, abs_io_, is used. 
When an absentee process is being created, absentee_real_init_admin_ obtains the 
arguments to the absentee process; it then makes them available to the abs_io_ 
I/O module and informs this module of the locations of the input and output 
segments. If a CPU time limit has been specified for the absentee process, 
absentee_real_init_admin_ also starts a timer with this limit value; the process 
is logged out when this value is reached. | 


The final action taken by the appropriate init_admin_ procedure is to 
locate the process overseer procedure named in the PIT and to call it. If the 
process overseer cannot be located or accessed, the appropriate init_admin_ 
procedure signals an error to the system control process, and the user is logged 
out with the message "Process cannot be initialized". 


Process Overseer Functions 


If an unclaimed signal reaches the appropriate init_admin_ procedure, the 
user process is terminated on the assumption that the process could not be 
initialized. Therefore, one of the first things that the process overseer 
procedure does is establish an appropriate handler for all conditions that could 
be specified. The standard system process overseer does this by executing: 


call condition_ ("any_other", standard_default_handler_) ; 


The standard_default_handler_ procedure is invoked on all signals not 
intercepted by any subsequently established condition handler. In general, the 
standard_default_handler_ procedure either performs some default action (such as 
inserting a pagemark into the stream when an endpage condition is signalled) and 
restarts execution, or else it prints a standard error message and calls the 
current listener. 


A process overseer procedure may perform many other actions besides those 
executed by the system version. For example, initialization of special 
per-project accounting procedures may be accomplished at this point or requests 
issued for an additional password or any other administrative information 
required by a project. 
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The system process overseer terminates processing by calling the standard 
listener in the following manner: : 


call listen_ (initial_command_line); 
The initial command line used by the system process overseer is: 


exec_com home_dir>start_up start_type proc_type 


where: 

Te start_type is either login or new_proc, depending on which of these was 
invoked to create the process. 

2. proc_type is either interactive or absentee. 


These arguments can be used by the start_up.ec segment as described in 
connection with the exec_com command in the MPM Commands. 


| The command line given above assumes that the no_start_up flag is off and 
that the segment named Sstart_up.ec can be found in the user's home directory. 
The no_start_up flag is off unless the project administrator has given the user 
the no_start_up attribute and the user has included the proper control. argument 
(-no_start_up or -ns) in his login line. 


If no start_up.ec segment is provided, or if one is provided but the 
no_start_up flag is on, the standard Multics process overseer checks the brief 
' Switch in the PIT. If this switch is off, and if the process was not created in 
response to a new_proc command or process’ termination Signal, the process 
overseer prints the contents of the message_of_the_day segment located in the 
directory named >system_control_1. 


The standard process overseer does not expect the listener to return. If 
it does, the appropriate init_admin_ procedure is recalled and the process is 
logged out with the message Process cannot be initialized. 


andling of Qui ignals 


A quit signal is indicated by pressing the appropriate key, such as ATTN or 
BRK, on the terminal in use. When a terminal is first attacned for interactive 
processing, quit signals from the terminal are disabled. A user quit signal 
issued at this time causes the flushing of terminal output buffers, but the quit 
condition is not raised in the user ring. The recognition of quit signals is 
enabled when the following call is made: 


call iox_$control (iox_$user_io, "quit_enable", null(), status); 


If a project administrator wishes to replace the standard user’ environment 
with his own o»rograms, he must find an appropriate place for the quit_enable 
order, after the mechanism for handling quit signals has been established. 
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SECTION IV 


IMPLEMENTATION TO INPUT/OUTPUT MODULES 


This section contains information applicable to writing I/0 modules. It 
describes the format and function of I/0 control blocks, provides a list of 
implementation rules, and describes the use of certain iox_ subroutine entry 
points necessary in I/O module construction. These entry points are described 
in more detail in Section)VII. For descriptions of the other iox_ entry points, 
refer to the MPM Subroutines. 


Some instances in which a user might wish to create a new I/O module are 
given below. 


1. Pseudo Device or File. An I/O module could be used to simulate I/0 
to/from a device or file. For example, it might provide a sequence of 
random numbers’ in response to an input request. The discard_ system 
I/O module (described in the MPM Subroutines) is an example of this 
Sort of module. | | 


2. New File Type. An I/O module could be used to Support a new type of 
file in the storage system, such as a file in which records have 
multiple keys. 


Se Reinterpreting a File. An I/O module could be designed to overlay a 
new structure (relative to the standard file types) on a standard type 
of file. For example, an unstructured file might be interpreted as a 
Sequential file by considering 80 characters as a record. 


‘4, Monitoring a Switch. An I/0 module could be designed to pass 
operations along to another module while monitoring them in some way 
(e.g., by copying input data to a file). 


on Unusual Devices. Working through the tty_I/0 module (described in 
the MPM Subroutines) in the raw mode, another I/0 module might 
transmit data to/from a device that is not a standard Multics device 
type (as regards character codes, etc.).. | 


The last three items listed illustrate a common arrangement. The user 
attaches an I/O switch, x, using an I/O module, A. To implement the attachment, 
module A attaches another switch, y, using another I/O module, B. When the user 
calls module A through the switch x, module A in turn calls module B through the 
Switch y. Any nonsystem I/O module that performs true I/O works in this way, 
because, it (or some module that it calls) must call a system I/O module. There 
are system I/O routines at a more primitive level than the I/0 modules, but 
user-written I/O modules must not call these routines. . 
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I/Q CONTROL BLOCKS 


Each I/0 switch has an associated I/O control block that is created the 
first time a call to iox_$find_iocb requests a pointer to the control block. 
The control block remains in existence for the life of the process unless 
explicitly destroyed by a call to iox_$destroy_ioeb. 


The principal components of an I/O control block are pointer variables and 
entry variables whose values describe the attachment and opening of the I/0 
Switch. There is one entry variable for each I/O operation with the exception 
of the attach operation. To perform an I/O operation through the switch, the 
corresponding entry value in the control block is called. For example, if 
iocb_ptr is a pointer to an I/0 control block, the call: 


call iox_$put_chars (iocb_ptr, buff_ptr, buff_len, code); 
results in the call: 
call iocb_ptr->iocb.put_chars (iocb_ptr, buff_ptr, buff_len, code); 


Certain system routines are allowed to make the latter call directly, without 
going through the iox_ subroutine; all other routines must call the iox_ 
subroutine. ; 


I/Q Control Block Structure 


The declaration given below describes the first part of an I/0 control 
block. Only those few I/O system programs that use the remainder of the I/0 
control block declare the entire block. Thus, all references to I/O control 
blocks here refer only to the first part of the control block. For example, the 
statement "no other changes are made to the control block" means that no other 
changes are made to the first part of the control block, and so on. The I/0 
System might make changes to the remainder of the block, but these are of 
interest only to the I/O system. For full details on the entry variables, see 
the descriptions of the corresponding entries in the iox_ subroutine in the MPM 
Subroutines. 


del 1 ioecb aligned, 
2 iocb_version fixed bin init(1), 
2 name char(32), 
2 actual_iocb_ptr ptr, 
2 attach_descrip_ptr ptr, 
2 attach _data_ptr ptr, 
2 open_descrip_ptr ptr, 
2 open_data_ptr ptr, 
2 reserved bit(72), 
2 detach_iocb entry (ptr, fixed bin(35)), 
2 open entry (ptr, fixed bin, bit(1) aligned, 
| fixed bin(35)), 
2 close entry (ptr, fixed bin(35)), 
2 get_line entry (ptr, ptr, fixed bin(21), fixed bin(21), 
fixed bin(35)), 
2 get_chars entry (ptr, ptr, fixed bin(21), fixed bin(35)), 
2 put_chars entry (ptr, ptr, fixed bin(21), fixed bin(35)), 
2 modes entry (ptr, char(*), char(#), fixed bin(35)), 
2 position entry (ptr, fixed bin, fixed bin(21), 


fixed bin(35)), 


- 
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2 control entry (ptr, char(#), ptr, fixed bin(35)), 

2 read_record entry (ptr, ptr, fixed bin(21), fixed bin(21), 
fixed bin(35)), | 

2 write_record entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 rewrite_record entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 delete_record entry (ptr, fixed bin(35)), 

2 seek_key entry (ptr, char(256) varying, fixed bin(21), 
fixed bin(35)), 

2 read_key entry (ptr, char(256) varying, fixed bin(21), 
fixed bin(35)), | 

2 read_length entry (ptr, fixed bin(21), fixed bin(35)); 

tach nter 


If the I/0 switch is detached, the value of iocb.attach_descrip ptr is 
null. If the I/O switch is attached, the value is a pointer to the following 
Structure: : 


del 1 attach_descrip based aligned, 
2 length fixed bin(17), 
2 string char (0 refer (length)); 


The value of attach_descrip.string is the attach description. See "Multics 
Input/Output System" in Section IV of the MPM Reference Guide for details on the 
attach description. A 


If the I/0 switch is detached, the value of iocb.attach_data_ptr is null. 
If the I/O switch is attached, the value may be null, or it may be a pointer’ to 
. data used by the I/0 module that attached the switch. To determine whether the 
I/O switch is attached or not, the value of iocb.attach_descrip ptr should be 
examined, it if it null, the switch is attached. 


en nver 


If the 1/0 switch is closed (whether attached or detached), the value of 
Llocb.open_descrip_ptr is null. If the switch is open, the value is a pointer to 
the following structure: 


dcl 1 open_descrip based aligned, 
2 length fixed bin(17), 
2 string char (0 refer (length)); 
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The value of open_descrip.string is the open description. It has’ the 
following form: 


mode -info- 


where: 


Vg mode is one of the opening modes (e.g., stream_input) listed below. The 
modes and their corresponding numbers are: 


Sstream_input 
Sstream_output 
stream_input_output 
sequential_input 
sequential output 
sequential_input_output 
sequential_update 
keyed_sequential_ input 
keyed_sequential_output 
10 keyed_sequential_update 
11 direct_input 

12 direct_output 

13 direct_update 
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25 info is other information about the opening. If info occurs in the 
String, it is preceded by one blank character. 


If the I/0 switch is closed, the value of iocb.open_data_ptr is null. If 
the I/O switch is open, the value may be null, or it may be a pointer to data 
- used by the I/O module that opened the switch. 


Entry Variables 


The value of each entry variable in an I/O control block is an entry point 
in an external procedure. When the I/O switch is in a state that Supports a 
particular operation, the value of the corresponding entry variable is an entry 
point that performs the operation. When the I/O switch is in a state that does 
not support the operation, the value of the entry variable is an entry point 
that returns an appropriate error code. 


Synonyms 


When an I/O switch named x is attached as a synonym for an I/O switch named 
y, the values of all entry variables in the I/0 control block for x are 
identical to those in the I/0 control block for’ y with the exception of 
iocb.detach. Thus a call: 


call iocbx_ptr->iocb.op(ioecbx_ptr,...); 


immediately goes to the correct routine. 
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The values of iocb.open_descrip ptr and iocb.open_data_ptr for x are also 
the same as those for y. Thus, the I/O routine has access to its open data (if 
any) through the I/O control block pointed to by iocbx_ptr. 


The value of iocb.actual_iocb_ptr for x is a pointer to the control block 
for the switch that is the ultimate target of a chain of Synonyms. (When the 
Switch x is not attached as Synonym, this pointer points to the control block 
for x itself.) I/0 modules use this pointer to access the ultimate I/O control 
block whose contents are to be changed, for example, when a switch is Opened. 
The I/O system then propagates the changes to other control blocks as required 
by synonym attachments. | 


WRITING AN I/O MODULE 


The information presented in the following paragraphs pertains to the 
design and programming of an I/O module. In particular, conventions are given 
that must be followed if the I/O module is to interface properly with the I/O 
System. The reader should be familiar with the material presented under the 
headings "Multics Input/Output System" and "File Input/Output" in Section IV of 
the MPM Reference Guide, the iox_ subroutine in the MPM Subroutines, and under 
"I/O Control Blocks" above. 


esi ideratio 


Before programming begins on an I/0 module, the functions it is to perform 
Should be clearly specified. In particular, the designer should list the 
opening modes to be supported and consider the meaning of each I/O operation 
Supported for those modes. (See "Open Pointers" above for a list of opening 
-Mmodes.) The specifications in the description of the iox_ subroutine must be 
related to the particular I/0 module (e.g., what seek_key means for the discard_ 
I/O module). 3 


An I/0 module contains routines to perform attach, open, close, and detach 
operations and the operations Supported by the opening modes. Typically, though 
not necessarily, all routines are in one object See If the module is a 
bound segment, only the attach entry need be retained as an external entry. 


Other routines are accessed through entry variables in I/O control blocks. 


An I/O module may have several routines that perform the same function but 
in different situations (e.g., one get_line routine for stream_input openings, 
another for stream_input_output openings). Whenever the situation changes 
(e.g., at opening), the module stores the appropriate entry values in the I/0 
control block. 
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implementation Rules 


The following rules apply to the implementation of all I/0 operations. 


Additional 
In the rul 


rules that are specific to a particular operation are given later. 
es, iocb is a based variable declared as described under "I/O Control 


Blocks" above, and iocb_ptr is an argument of the operation in question. 


Except for attach, the usage (entry declaration and parameters) of a 
routine that implements an I/O operation is the same as the usage of 
the corresponding entry in the iox_ Subroutine. see the MPM 
Subroutines for details on the iox_ subroutine. 


Except for attach and detach, the actual I/O control block to which an 
operation applies (i.e., the control block attached by the called I/0 
module) must be referenced using the value of 
iocb_ptr->iocb.actual_iocb_ptr. It is incorrect to use just iocb_ptr, 
and it is incorrect to remember the location of the control block from 
a previous call (e.g., by storing it in a data structure pointed to by 
iocb.open_data_ptr). 


On entry to an I/O module, the value of iocb_ptr->iocb.open_data_ptr 
always equals the value of: 


iocb_ptr->iocb.actual_iocb_ptr->iocb.open_data_ptr 
The value of ptr->iocb.open_descrip_ptr always equals the value of: 
locb_iocb_ptr->iocb.actual_iocb_ptr->iocb.open_descrip_ ptr 


Thus, the data structures related to an opening may be accessed 
without going through iocb.actual_iocb_ptr. 


If an I/O operation changes any values in an I/O control block, it 
must be the actual I/0 control block (Rule 1 above); and, before 
returning, the operation must execute the call: 


call iox_$propagate (p); 
where p points to the changed control block. The routine 
iox_$propagate reflects changes to other control blocks attached as 
Synonyms. It also makes certain adjustments to the entry variables in 
the control block when the I/O switch is attached, opened, closed, or 
detached. 


All I/O operations must be external procedures. 
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ac 


The 


eratio 


name of the routine that performs the attach operation is derived by 


concatenating the word "attach" to the name of the ‘I/O module (e.g., 


discard_attach is the name of the attach routine for the discard_ I/O module). 
Each attach’ routine has the following usage: 7 


declare module_nameattach entry (ptr, (*)char(*) varying, bit(1) aligned, 


fixed bin(35)); 


call module_nameattach (iocb_ptr, option_array, com_err_switch, code); 


where: 


ie 


iocb_ptr points to. the control block of the I/0 switch to be 
attached. (Input) 

option_array contains the options in the attach description. If there 
are no options, its bounds are (0:0). Otherwise, its bounds 
are (1:n) where n is the number of options. (Input) 

com_err_switch indicates whether the attach routine should call the 


code 


com_err_ subroutine (described in the MPM Subroutines) when 
an error is detected. (Input) 

"1"b yes ! 

Noth no 


is a standard system status code. (Output) 


The following rules apply to coding an attach routine: 


If the I/0 switch is already attached (i.e., if 
iocb_ptr->iocb.attach_descrip ptr is not null), return the code 
error_table_$not_detached; do not make the attachment. 


If, for any reason, the switch cannot be attached, return an 
appropriate nonzero code and do not modify the control block. Call 
the com_err_ subroutine if, and only if, com_err_switch is "1"b. If 
the attachment can be made, follow the remaining rules and return with 
code set to 0. | 


Set iocb_ptr->iocb.open and iocb_ptr->iocb.detach_iocb to the 


appropriate open and detach routines. In addition, set 


iocb_ptr->attach_descrip_ ptr to point to a structure as described in 
"I/O Control Blocks" above. The attach description in this structure 
must be fabricated from the options in the argument option array, and 
there may be some modification of options, e.g., expanding a pathname. 


If desired, set iocb_ptr->iocb.attach_data_ptr, iocb_ptr->iocb.modes, 


and iocb_ptr->iocb.control. Make no other modifications to the 
control block. 
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Open Qperation 


(through 


An open operation is performed only when the actual I/O switch is attached 


the I/0 module containing the routine) but not open. The following 


rules apply to coding an open routine: 


lose 


If, for any reason, the opening cannot be performed, return an 
appropriate code and do not modify the I/O control block. If the 
opening can be performed, follow the remaining rules and return with 
code set to 0. 


Set iocb_ptr->iocb.actual_iocb_ptr->iocb.op (where op is any operation 
listed under "Qpen Pointers" above) to an appropriate routine. This 
applies for each operation allowed for the Specified opening mode. 
If either the modes operation or the control operation is enabled with 
the I/O Switch attached but not open, set 
iocb_ptr->iocb.actual_iocb_ptr->iocb.op (where op is modes or control) 
to iox_$err_no_operation. 
Set open_descrip_ptr to point to a structure as described in "T/0 
Control Blocks" above. 
If desired, set iocb_ptr->iocb.actual_iocb_ptr->iocb.open_data_ptr. 
Do not make any other modifications to the control block. 

eration 


A close operation is performed only when the actual I/O switch is open, the 
opening having been made by the I/O module containing the close routine. The 
following rules apply to coding a close routine: 


Va 


set the following to the appropriate open and detach routines: 


iocb_ptr->iocb.actual_iocb_ptr->iocb.open 
iocb_ptr->iocb.actual_iocb_ptr->iocb.detach_iocb 


set iocb_ptr->iocb.actual_iocb_ptr->iocb.open_descrip ptr to null. 
If either the modes operation or the control operation is enabled with 


the switch open, set iocb_ptr->iocb.actual_iocb_ptr->iocb.op, where op 
is modes or control. Unless the operation is enabled with the switch 


closed, set the entry variable to iox_$err_no_operation. 


Do not make any other modifications to the control block. 

The close routine should set the bit counts on modified segments of a 
file, free any storage allocated for buffers, etc., and in general, 
clean things up. 


The close routine must not return without closing the switch. 
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Detach Operation 


A detach operation is performed only when the actual I/O switch is attached 
but not open, the attachment having been made by the I/O module containing the 
detach routine. The following rules apply to coding detach routines: 


lie Set iocb_ptr->iocb.attach_descrip_ptr to null. 
2% Do not make any other modifications to the control block. 


a The detach routine must not return without detaching the switch. 


ontrol rations. 


These operations can be accepted with the I/O switch attached but closed; 
however, it is generally better practice to accept them only when the switch is 
open. 


If the control operation is supported, it must return the code 
error_table_$no_operation when given an invalid order. In this situation, the 
state of the I/0 switch must not be changed. 


! 


If the modes operation is supported, it must return the code 
error_table_$bad_mode when given an invalid mode. 


Routines for the other operations are called only when the actual I/0 
Switch is attached and open in a mode for which the operation is allowed, the 
opening and attachment having been made by the I/O module containing the 
routine. In coding these routines, make only the following modifications to the 
I/0 control block of the actual I/O switch. 


Tk Reset iocb_ptr->iocb.actual_iocb_ptr->iocb.open_data_ptr. 


2s Reset an entry variable set by the open routine, e.g., to switch from 
one put_chars routine to another. 


3% Close the switch in an error situation. In this case, the rules above 
for the close operation must be followed. 
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SECTION V 


REFERENCE TO COMMANDS AND SUBROUTINES BY FUNCTION 


COMMAND REPERTOLRE 


The Multics commands described in this manual are organized by function 


into the following categories: 


Debugging and Performance Monitoring Facilities 
Language Translators, Compilers, Assemblers, and Interpreters 


Object Segment Manipulation 
Storage System, Access Control 


Storage System, Directory Manipulation 
Storage System, Mailbox Manipulation 
Storage System, Segment Manipulation 


Detailed descriptions 


t 


these commands, arranged alphabetically rather 


than functionally, are given in Section VI of this document. In addition, many 
of the commands have online descriptions, which the user may obtain by invoking 
the help command (described in the MPM Commands). 


See "Reference to Commands By Function" in Section I of the MPM Commands 
for the functional grouping of the commands described in that manual. 


Debugging and Performance Monitoring Facilities 


area_Status 

create_area 
delete_external_ variables 
display_component_name 
list_external_variables 


list_temp_segments 
print_linkage_usage 


reset_external_variables 
set_system_storage 


set_user_storage 
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displays information about an area 

creates an area and initializes it 

deletes specified variables managed by the 
system 

converts bound segment offset into referenced 
component object segment offset 

prints information about variables managed by 
the system 


lists segments in temporary segment pool 


prints block storage usage for combined 
linkage regions 

reinitializes system managed variables 

establishes an area as the storage region for 
normal system allocations 

establishes an area as the storage region for 
normal user allocations 
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L Tr r Compiler Ass ler dqd If rpreters 


alm invokes ALM assembler 
alm_abs invokes ALM assembler in absentee job 
error_table_compiler compiles table of status codes and messages 


from ASCII source segments 


Object Segment Manipulation 


print_bind_map prints bind map of object segment 

print_link_info prints information about object segments 
Storage System, Access Control 

set_ring_ brackets changes ring brackets of segment 


Storage System, Directory Manipulation 


copy_names copies names from one segment to another 

move_names moves names from one segment to another 

set_max_length specifies maximum length of nondirectory 
segment 


Storage System, Mailbox Manipulation 


mbx_add_name adds alternate names to mailbox 

mbx_create creates mailbox 

mbx_delete deletes mailbox 

mbx_delete_acl deletes entries from mailbox ACL 

mbx.delete_name deletes name from mailbox 

mbx_list_acl lists ACL of mailbox 

mbx_rename replaces one name with another on mailbox 

mbx_set_acl adds and changes entries on mailbox ACL 

mbx_set_max_length sets maximum length of a mailbox segment 
stor e t Mani 

archive_sort sorts components of archive segment 

reorder_archive orders components of archive segment 


SUBROUTI REPER 


The Multics subroutines described in this manual are organized by function 
into the following categories: 


Clock and Timer Procedures 

Command Environment Utility Procedures 
Condition Mechanism 

Data Type Conversion Procedures 
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Error Handling Procedures 

Input/Output System Procedures 

Miscellaneous Procedures 

Object Segment Manipulation 

Process Synchronization 

Storage System, Access Control and Rings of Protection 
Storage System, Address Space 

Storage System, Directory and Segment Manipulation 
Storage System, Utility Procedures 


Since many subroutines can perform more than one function, they are listed 
in more than one group. 


Detailed descriptions of these subroutines, arranged alphabetically rather 
than functionally, are given in Section VII of this document. 


Many of the functions provided by these subroutines are also available as 
part of the runtime facilities of Multics- supported programming languages; users 
are encouraged to use the language-related facilities wherever possible. 


see "Introduction to Standard Subroutines" in Section Il of the MPM 
Subroutines for the functional grouping of the subroutines described in that 
manual. 


Clock and Timer Procedures 
timer_manager_ allows user process interruption after 
specified amount of CPU or real-time 
passes 
C nd Envir Utili P r 
check_star_name_ verifies formation of entrynames according to 
| star name rules 
Cu_. command utility programs provide functions 
needed by command and subsystem writers 
get_default_wdir_ returns pathname of user's current default 
working directory 
get_definition_ returns pointer to specified definition 
within an object segment 
get_entry_name_ returns associated name of externally defined 
location or entry point in segment 
get_equal_name_ constructs target name by substituting from 
entryname into equal name 
get_system_free_area_ returns pointer to system free area for 
calling ring 
C iti ec ism 
condition_interpreter_ prints formatted error message for most 
conditions 
continue_to_sSignal_ enables on unit that cannot completely handle 


condition to tell signalling program to 
search stack for other on units for 
condition 
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find_condition_info_ 


prepare_mc_restart_ 


Signal_ 
unwinder_. 


ascii_to_ebedic_ 
assign_ 


ev_bin_ 


ev_entry_ 
ev_hex_ 


Cv_oct_ 


Cv_ptr_ 
ebcdic_to_ascii_ 


E Ha j Procedur 


active_fnc_err_ 
convert_status_code_ 


Sub_err_ 


I t /0 P 
convert_dial_message_ 
dial_manager_ 
dprint_ 


iod_info_ 


Mi e Pr 


decode_descriptor_ 
get_privileges_ 


sys_info 
system_info_ 
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re 


returns information about condition when 
Signal occurs 

checks machine conditions for restartability, 
and permits modifications to them for 
user changes to process execution, before 
condition handler returns 

Signals occurrence of given condition 

performs nonlocal goto on Multics stack 


performs conversion from ASCII to EBCDIC 

assigns specified source value to _ specified 
target performing required conversion 

converts binary representation of integer to 
12-character ASCII string 

converts a virtual entry to an entry value 

returns the fixed binary representation of an 
ASCII hexadecimal integer 

converts) ASCII representation of octal 
integer to fixed binary representation of 
that number 

converts a virtual pointer to a pointer value 

performs conversion from EBCDIC to ASCII 


prints formatted error message and _ signals 
active_function_error condition 

returns short and long status messages for 
given status code 

reports errors detected by other subroutines 


controls dialed terminals 

interfaces the answering service dial 
facility 

adds segment print or _ punch request to 
specified queue 

extracts information from I/O daemon tables 
for commands and subroutines submitting 
I/O daemon requests 

provides interfaces for controlling the data 
structures of the I/O system 

supports I/0 from/to segments and 
multisegment files in the storage system 


“extracts information from argument 


descriptors 
returns process! access privileges 
is a wired-down, per-system data base 
provides user with information on _ system 
parameters 
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Object Segment Manipulation 


ob ject_info_ 


Process Synchronization 
hes_$wakeup 


ipe 


S Acc n 


aim_check_ 


convert_aim_attributes_ 


get_privileges_ 

get_ring_ 
hes_$add_dir_inacl_entries 
hes_$add_inacl_entries 
hes_$delete_dir_inacl_entries 
hes_$delete_inacl_entries 
hes_$get_dir_ring_brackets 
hes_$get_ring_ brackets : 
hes_$list_dir_inacl 
hes_$list_inacl 
hes_$replace_dir_inacl 
hes_$replace_inacl 
hes_$set_dir_ring brackets 
hes_$set_ring_brackets 
read_allowed_ 
read_write_allowed_ 
write_allowed_ 


S dr 


hes_$get_search_rules 
hes_$get_system_search_rules 
hes_$initiate_search_rules 
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prints structural and identifying information 
extracted from object segment 

retrieves information from object segment's 
(PL/I or FORTRAN) runtime symbol table 
section 

simplifies use of storage system by language 
translators 


sends interprocess communication wakeup to 
blocked process over specified event 
channel 

user interface to Multics interprocess 
communication facility 


determines relationship between two access 
attributes. 

converts representation of process'/segment's 
access authorization/class into character 
string of defined form 

returns process! access privileges 

returns number of current protection ring 

adds specified access modes to initial ACL 
for segments or directories | 

deletes specified entries from initial ACL 
for segments or directories 

returns ring brackets for specified segment 
or subdirectory 

returns all or part of initial ACL for 
segments or directories 

replaces initial ACL with user-provided one 
for segments or directories 

sets ring brackets for specified segment or 
directory | 

determines if AIM allows specified operations 
on object given process! authorization 
and object's access class 


returns user's current search rules 
prints site-defined search rule keywords 
allows user to specify search rules 
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hes_$del_dir_tree 
hes_$get_author 
hes_$get_be_author 


hes_$get_max_length } 
hes_$get_max_length_seg 
hes_$get_safety_sw } 
hes_$get_safety_sw_seg 
hes_$quota_move 


hes_$quota_read 
hes_$set_entry_bound } 
hes_$set_entry_bound_seg 
hes_$set_max_length 
hes_$set_max_length_seg 
hes_$set_safety_sw } 


hes_$set_safety_sw_seg 
hes_$star_ 


Storage System, Utility Procedures 


area_info_ 
define_area_ 
get_default_wdir_ 
get_definition_ 
get_entry_name_ 
get_equal_name_ 
match_star_name_ 


msf_manager_ 


release_area_ 
tssi_ 
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deletes subdirectory's contents 

returns author of segment, directory, or link 

returns bit-count author of a segment or 
directory 

returns maximum length of segment, 


returns safety switch value of directory or 


segment 

moves all or part of quota between two 
directories 

returns record quota and accounting 


information for directory 
sets entry point bound of segment 


sets maximum length of segment 
sets safety switch of segment 


returns storage system type and all names 
that match entryname according to star 
name rules 


returns information about an area 

initializes a region of storage as an area 

returns pathname of user's current default 
working directory 

returns pointer’ to specified definition 
within an object segment | 

returns associated name of externally defined 
location or entry point in segment 

constructs target name by substituting from 
entryname into equal name 

compares entryname with star name 

provides the means for multisegment files to 
create, access, and delete components, 
truncate the file and control access 

cleans up an area 

Simplifies use of storage system by language 
translators 
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SECTION VI 


COMMANDS 


COMMAND DESCRIPTION FORMAT 


This section contains descriptions of the Multics commands, presented in 
alphabetical order. Each description contains the name of the command 
(including the abbreviated form, if any), discusses the purpose of the command, 
and shows the correct usage. Notes and examples are included when deemed 
necessary for clarity. The discussion below briefly describes the content of 
the various divisions of the command descriptions. 


Name 


The "Name" heading lists the full command name and its abbreviated form. 
The name is usually followed by a discussion of the purpose and function of the 
command and the expected results from the invocation. - 


Usage 


This part of the command description first shows a single line that 
demonssrates the proper format to use when invoking: the command and then 
explains each element in the line. The following conventions apply in the usage 
line.. | 


1. Optional arguments are enclosed in braces (e.g., {path}, {User_ids}). 
All other arguments are required. 7 


2. Control arguments are identified in the usage line with a leading 
hyphen (e.g., {-control_args}) simply as a reminder that all control 
arguments must be preceded by a hyphen in the actual invocation of the 
command. 


3 To indicate that a command accepts more than one of a _ specific 
argument, an "s" is added to the argument name (e.g., paths, {paths}, 
{-control_args}). | | 


NOTE: Keep in mind the difference between a plural argument name that is 
enclosed in braces. (i.e., optional) and one that is not (i.e., 
required). If the plural argument is enclosed in braces, clearly no 
argument of that type need be given. However, if there are no 
braces, at least one argument of that type must be given. Thus 
"paths" in a usage line could also be written as: 
pathi {path2 ... pathn} 
The convention of using "paths" rather than the above is merely a 
method of saving space. 
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4, Different arguments that must be given in pairs are numbered (e.g., 
xxx] yyyl i... xxxn yyyn}). 


on To indicate that the same generic argument must be given in pairs, the 
arguments are given letters and numbers (e.g., pathAl pathBi {... 
pathAn pathBn}). 


6. To indicate one of a group of the same arguments, an "i" is added to 
the argument name (e.g., pathi, User_idi). 


To illustrate these conventions, consider the following usage line: 
command ipaths} {-control_args} 
The lines below are just a few examples of valid invocations of this command: 


command 

command path path 

command path -control_arg 

command -control_arg -control_arg 

command path path path -control_arg -control_arg -control_arg 


In many cases, the control arguments take values. For simplicity, common 
values are indicated as follows: 


STR any character string; individual command descriptions indicate 
any restrictions (e.g., must be chosen from specified list; must 
not exceed 136 characters). 


N number; individual command descriptions indicate whether it is 
octal or decimal and any other restrictions (e.g., Cannot be 
greater than 4). 


DT date-time character string in a form acceptable to the 
convert_date_to_binary_ subroutine described in the MPM 
Subroutines. 

path pathname of an entry; unless’. otherwise indicated, it may be 


either a relative or an absolute pathname. 


The lines below are samples of control arguments that take values: 


-access_name STR, -an STR 
-ring N, -rg N 

-date DT, -dt DT 
-home_dir path, -hd path 


Notes 


Comments or clarifications that relate to the command as a whole are given 
under the "Notes" heading. Also, where applicable, the required access’ modes, 
the default condition (invoking the command without any arguments), and any 
special case information are included. 
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Examples 


The examples show different valid invocations of the command. An 
exclamation mark (!) is printed at the beginning of each user-typed line. This 
is done only to distinguish user-typed lines from system-typed lines. The 
results of each example command line are either shown or explained. 


Other Headings 


Additional headings are used in some descriptions, particularly the more 
lengthy ones, to introduce specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 
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ALM is the standard Multics assembly language. It is commonly used for 
privileged supervisor code, higher level support operators and utility packages, 
and data bases. It is occasionally used for efficiency or for hardware features 
not accessible in higher level languages; however, its routine use is 
discouraged. 


The alm command invokes the ALM assembler to translate a segment containing 
the text of an assembly language program into a Multiecs standard object segment. 
A listing segment can also be produced. These segments are placed in the user's 
current working directory. 


The ALM language is described briefly in this command description. The 
Multics Processor Manual, Order No. AL39, fully describes the instruction set. 


Usage 


alm path {-control_args} 


where: 
1. path 
is the pathname of an ALM source segment that is to be translated by 
the ALM assembler. If path does not have a suffix of alm, one is 
assumed. However, the suffix must be the last component of the name 
of the source segment. 
2s control_args 
: are optional arguments that can only appear after the path argument. 
The control arguments are: 
-list, -ls 
produces an assembly listing segment. 
-no_symbols 
Suppresses the listing of a cross-reference table in the listing 
segment. This cross-reference table is included by default in the 
listing segment when the -list control argument is given. 
-brief, -bf 
prevents errors from being printed on the terminal. Any errors are 
flagged in the listing (if one has been requested). 
Notes 


The only result of invoking the alm command without control arguments is’ to 
generate an object segment. 
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A successful assembly produces an object segment and leaves it in the 
user's working directory. If an entry with that name existed previously in the 
directory, its access control list (ACL) is saved and given to the new copy. 
Otherwise, the user is given re access to the segment with ring brackets v,Vv,Vv 
where v is the validation level of the process that is active when the object 
segment is created. | 


If the user specifies the -list control argument, the alm command creates a 
listing segment in the working directory and gives it a name consisting of the 
entryname portion of the source segment with the suffix list rather than alm 
(e.g., a Source segment named prt_conv_.alm would have a listing segment named 
prt_conv_.list). The ACL is .as described for the object segment except that the 
user is given rw access to the newly created segment. Previous copies of the 
object segment and the listing segment are replaced by the new segments’ created 
by the compilation. 


The assembler is serially reusable and sharable, but cannot be reentered 
once translation has begun; that is, it cannot be interrupted during execution, 
invoked again, then restarted in its previous invocation. 


rror Condition 


Errors arising in the command interface, such as inability to locate the 
source segment, are reported in the normal Multics manner. Some conditions can 
arise within the assembler that are considered malfunctions in the assembler; 
these are reported by a line printed on the terminal and also in the listing. 
Any of the above cases is immediately fatal to the translation. 


Errors detected in the source program, such as undefined symbols, are 
reported by placing one-letter error flags at the left margin of the erroneous 
line in the listing segment. Any line so flagged is also printed on the user's 
terminal, unless the -brief control argument is in effect. Flag letters and 
their meanings are given below. 


B mnemonic used belongs to obsolete (Honeywell Model 645) processor 
instruction set | 


E malformed expression in arithmetic field 

PF error in formation of pseudo-operation operand field 

M reference to a multiply defined symbol 

N unimplemented or obsolete pseudo-operation 

O unrecognized opcode 

Pp phase error; location counter at this statement has changed between 
passes, possibly due to misuse of org pseudo-operation 

R expression produces an invalid relocation type 

S error in the definition of a symbol 

T undefined modifier (tag field) 
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U reference to an undefined symbol 


vi digit 8 or 9 appears in an octal field 


The errors B, E, M, O, P, and U are considered fatal. If any of them 
occurs, the standard Multics "Translation failed" error message is _ reported 
after completion of the translation. 


ALM Language 


An ALM source program is a sequence of statements separated by newline 
characters or semicolons. The last statement must be the end pseudo-operation. 


Fields must be separated by white space, which is defined to include space, 
tab, new page, and percent characters. 


A name is a sequence of uppercase and lowercase letters, digits, 
underscores, and periods. A name must begin with a letter, period, or 
underscore and cannot be longer than 31 characters. 


Labels 


Each Statement can begin with any number of names, each followed 
immediately by a colon. Any such names are defined as labels, with the current 
value of the location counter. A label on a pseudo-operation that changes 
location counters or forces even alignment (such as org or its) might not refer 
to the expected location. White space is optional. It can appear before, 
after, or between labels, but not before the colon. 


OQpeode 


The first field after any labels is the opcode. It can be any instruction 
mnemonic or any one of the pseudo-operations listed later in this description 
under "Pseudo-operations." The opcode can be omitted, and any labels are still 
defined. White space can appear before the opcode, but is not required. 


Qperand 


Following the opcode, and separated from it by mandatory white space, is 
the operand field. For instructions, the operand defines the address, pointer 
register,, and tag (modifier) of the instruction. For each pseudo-operation, 
the operand field is described under "Pseudo-operations." The operand field can 
be omitted in an instruction. Those pseudo-operations that use their operands 
generally do not permit the operand field to be omitted. 
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Comments 


Since the assembler ignores any text following the end of the operand 
field, this space is commonly used for comments.  In_ those pseudo-operations 
that do not use the operand field, all text following the opcode is ignored and 
can be used for comments. Also, a quote character (") in any field introduces a 
comment that extends to the end of the statement. (The only exceptions are _ the 
ace, aci, and bei pseudo-operations, for which the quote character can be used 
to delimit literal character strings.) The semicolon ends a statement and 
therefore ends a comment as well. 


I r n nd 


The operand field of an instruction can be of several distinct formats. 
Most common is the direct specification of pointer register, address, and tag 
(modifier). This consists of three subfields, any of which can be omitted. The 
first subfield specifies a pointer register by number, user-defined name, or 
predefined name (prO, pri, pr2, pr3, pr4, pr5, pr6, pr7). The subfield ends 
with a vertical bar. If the pointer register and vertical bar are omitted, no 
pointer register is used in the instruction. The second subfield is any 
arithmetic expression, relocatable or absolute. This is the address part of the 
instruction, and its default is zero. Arithmetic expressions are defined below 
under "Arithmetic Expressions." The last subfield is the modifier or tag. Lt 
is separated from the preceding subfields by a comma. If the tag subfield and 
comma are omitted, no instruction modification is used. (This is an all zero 
modifier.) Valid modifiers are defined below under "Modifiers." 


Other formats of instruction operands are used to imply pointer registers. 
If a symbolic name defined by temp, tempd, or temp8 is used in the address 
subfield (it can be used in an arithmetic expression), then pointer register 6 
is used if no pointer register is specified explicitly. This form can have a 
tag subfield. 


Similarly, if an external expression is used in the address subfield, then 
pointer register 4 is implied; this causes a reference through a_ link. The 
pointer register subfield may not be specified explicitly. Ifa modifier 
subfield is specified, it is taken as. part of the external expression; the 
instruction has an implicit n* modifier to go through the link pair. External 
expressions are defined below under "External Expressions." 


A literal operand begins with an equal sign followed by a _ literal 
expression. The literal expression can be enclosed in parentheses. It has no 
pointer register but can have a tag subfield. A literal reference normally 
causes the instruction to refer to a word in a literal pool that contains the 
value of the literal expression. However, if the modifier du or dl is used, the 
value of the literal is placed directly in the instruction address field. 
Literal expressions are defined below under "Literal Expressions." 
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In j r 


Certain instructions assembled by the ALM assembler do not follow the 
Standard opcode-operand format as described above. These instructions fall into 
three basic classes: the repeat instructions, special treatment of the index 
and pointer register instructions, and EIS instructions. Each of these special 
cases is described below. 


REPEAT INSTRUCTIONS 


The repeat instructions are used to repeat either one or a pair of 
instructions until specified termination conditions are met. There are two 
basic forms: 


rpt tally,delta,term!,term2,...,termp 


generates the machine rpt instruction as described in the Multics Pr 
Manual. Both tally and delta are absolute arithmetic expressions. The termj 
Specify the termination conditions as the names of corresponding conditional 
transfer ‘instructions. This same format can be used with the rpt, rpd, rpda, 
and rpdb pseudo-operations. 


rptx ,delta 


generates the machine rpt instruction with a bit set to indicate that the tally 
and termination conditions are to be taken from index register 0. This format 
can be used with rplx and rpdx. 


INDEX REGISTER INSTRUCTIONS 


The opcodes for manipulation of the index registers have the general form 
opxn, where yn specifies the index register to be used in the operation. ALM 
allows the more general form: 


opx index,operand 


which assembles opxn, where index is an absolute arithmetic expression whose 
value is n. This format can be used for all index register instructions. 
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POINTER REGISTER INSTRUCTIONS 


As with the index register instructions, the opcodes for the manipulation 
of the pointer registers have the general form oprn, where n specifies the 
pointer register to be used. ALM extends this form to allow: 


opr pointer, operand 


which assembles as oprn, where n is found as follows: If pointer is a built-in 
pointer name (pr0O, pri, etcec.), that register is selected; otherwise, pointer 
must be an absolute arithmetic expression whose value is n. This format can be 
used with all pointer register instructions except spri. 


EIS MULTIWORD INSTRUCTIONS 


,» 


An EIS multiword instruction consists of an operation code word, followed 


by one or more descriptor words. The descriptor words can be assembled by using 
the "desc" pseudo=-operations listed under "Pseudo-Operations" below. The 


operation code word has the following general form: 


eisop (MF1),(MF2),keyword1(octexpression) ,keyword2 


where: 
Tg MF1,MF2 are EIS modification fields as described in "EIS Modifiers" 
below. 
Zn keyword! can be either fill, bool, or mask. 
cae ‘octexpression is a logical expression that specifies the bits to be placed 
in the appropriate parts of the instruction. 
4, keyworde can be round, enablefault, or ascii; these cause _ single 


option bits in the instruction to be set. 


’ Keywords can appear in any order, before or after an MF field. This format 
can be used for all Multics EIS multiword instructions. 
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EIS SINGLEWORD INSTRUCTIONS 


The Multics processor contains a set of 10 instructions that may be used to 
alter the contents of an address register. These instructions have the 
following general form: 


opeode prioffset,modifier 


where: 

1. pr selects the address register that is to be modified by the 
instruction. 

2. offset is a value whose interpretation is dependent upon the _ opcode 
used. 


ce modifier must be one of the register modifiers (au, ql, x0, etc.). 


These instructions have two modes of operation depending on the setting of 
bit 29 in the instruction. If bit 29 is 1, the current contents of the selected 
address register are used in determining its new contents; if bit 29 is 0, the 
contents of the word and bit offset portions of the selected address register 
are assumed to be zero at the start of the instruction (this results in a load 
operation into the selected address register). ALM normally sets bit 29 to 1, 
unless the opcode ends in "x" (e.g., awdx is an awd instruction with bit 29 set 
to 0). This format can be used with a4bd, a6bd, a9bd, abd, awd, s4bd, s6bd, 
s9bd, sbd, and swd. 


xamples of Instruction Sta n 


Six examples of instruction statements are shown below. A brief 
description of each example follows the sample statements. | 


xlab: lda pr0j2,* | " Example 1. 


eax7 xlab-1 

recl <sys_info>i[clock_],* " Example 2. 
segref sys_info,time_delta " Example 3. 
adl time_delta+1 

temp nexti " Example 4. 
1x10 nexti, * | 
link goto, <unwinder_>;[unwinder_] " Example 5. 
tra pr4jgoto,* 

ana =o777777,du " Example 6. 
ada =v36/list_end-1 
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Example 1 shows direct specification of address, pointer register, and tag 
fields. In.the second instruction, no pointer register is specified, .and the 
symbol xlab is not external, so no pointer register is used. 


Example 2 shows an explicit link reference. Indirection is specified for 
the link as the item at clock_ (in sys_info) is merely a pointer to the final 
operand. ; 


Example 3 uses an external expression as the operand of the adl 
instruction. In this particular case, the operand itself is in sys_info. 


Example 4 uses a stack temporary. Since the word is directly addressable 
using pr6, the modifier specified is used in the instruction. 


Example 5 shows a directly specified operand that refers to an external 
entity. It is necessary in this case to specify the pointer register and 
modifier fields, unlike segref. : 


Example 6 uses two literal operands. Only the second instruction causes 
the literal value to be stored in the literal pool. 


r i n 


An arithmetic expression consists of names (other than external names) and 
decimal numbers joined by the ordinary operators + - * /. Parentheses can be 
used with their normal meaning. 


‘An asterisk in an expression, when not used as an operator, has the value 
of the current location counter. 


All intermediate and final results of the expression must be absolute or 
relocatable with respect to a single location counter. A relocatable expression 
cannot be multiplied or divided. | 


Logical Expressions 


A logical expression is composed of octal constants and absolute symbols 
combined with the Boolean operators + (OR), - (XOR), * (AND), and ~ (NOT). 
Parentheses can be used with their normal meaning. 
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xternal re 


An external expression refers symbolically to some other segment. It 
consists of an external name or explicit link reference, an optional arithmetic 
expression added or subtracted, and an optional modifier subfield. An external 
name is one defined by the segref pseudo-operation. An explicit link reference 
must begin with a segment name enclosed in "angle brackets" (the less-than and 
greater-than characters) and followed by a vertical bar. This can optionally be 
followed by an entryname in square brackets. For example: 


<segname>; [entryname ] 
<segname>;0,5* 


A segment name of *text, *link, or *static indicates a reference to this 
procedure's text, linkage, or static sections. 


A link pair is constructed for each combination of segment name, entryname, 
arithmetic expression, and tag that is referenced. 


Literal Expressions 


A literal reference causes the instruction to refer to a word in a literal 
pool that contains the value specified. However, the du and dl modifiers cause 
the value to be stored directly in the address field of the instruction. The 
various formats of literals are described in the following paragraphs. 


A decimal literal can be signed. If it contains a decimal point or 
exponent, it is floating point. If the exponent begins with "d" instead of "e", 
it is double precision. A binary scale factor beginning with "b" indicates 
fixed point and forces conversion from floating point. 


An octal literal begins with an "o" followed by up to 12 octal digits. 


ASCII literals can occur in two forms. One form begins with a decimal 
number between 1 and 32 followed by "a" followed by the number of data 
characters specified by the integer preceding the "a", which can cross statement 
delimiters. The other form begins with "a" followed by up to four data 
characters, which can be delimited by the newline character. 


A GBCD literal begins with "h" followed by up to six data characters, which 
can be delimited by the newline character. Translation is performed to the 
6-bit character code. 


An ITS (ITP) literal begins with "its" ("itp") followed by a parenthesized 
list containing the same operands accepted by the its (itp) pseudo-operation. 
The value is the same as that created by the pseudo-operation. 


A variable-field literal begins with "v" followed by any number of decimal, 
octal, and ASCII subfields as in the vfd pseudo-operation. It must be enclosed 
in parentheses if a modifier subfield is to be used. 
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These specify indirection, index register address modification, immediate 
operands, and miscellaneous tally word operations. They can be specified as 
2-digit octal numbers (particularly useful for instructions like stba) or 
symbolically using the mnemonics described here. 


Simple register modification is specified by using any of the register 
designators listed below. It causes the contents of the selected register to be 
added to the effective address. | 


Designators Register 

x0 0 index register 0 

x1 1 index register 1 

x2 2 index register e2 

x3 3 index register 3 

x4 4 index register 4 

x5 5 index register 5 

x6 6 index register 6 

x7 T index register 7 

n none (no modification) | 
au A bits 0-17 

al A bits 18-35 or 0-35 
qu Q bits 0-17 

ql Q bits 18-35 or 0-35 
ic instruction counter 


In addition to the above, any symbol that is not otherwise a valid modifier 
(e.g., au, ql, x7) may be used as a modifier to designate an index 
register. Thus, 


equ rege, 3 
lda spj}0,*rege 


‘is equivalent to: 


lda sp}0, #3 


 Register-then-indirect modification is specified by using any of the 
register designators followed by an asterisk. If the asterisk is used alone, it 
is equivalent to the n* modifier. The register is added to the effective 
address, then the address and modifier fields of the word addressed are used in 
determining the final effective address. Indirect cycles continue as long as 
the indirect words contain an indirect modifier. 


v 


Indirect-then-register modification is specified by placing an asterisk 
before any one of the register designators listed above. 


Direct modifiers are du and dl. They cause an immediate operand word to be 
fabricated from the address field of the instruction. For dl, the 18 address 
bits are right-justified in the effective operand word; for du they are 
left-justified. In either case, the remaining 18 bits of the effective operand 
are filled with O's. 
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Segment addressing modifiers are its and itp; they can only occur in an 
indirect word pair on a double-word boundary. The addressing modifier its 
causes the address field of the even word to replace the segment number of the 
effective address, then continues the indirect cycle with the odd word of the 
pair. Nearly all indirection in Multics uses ITS pairs. For itp, see the 


Multies Processor Manual. 


Tally modifiers i, ci, sc, ser, ad, sd, id, di, ide, and die control 
incrementing and decrementing of the address and tally fields in the indirect 
word. They are difficult to use in Multics because the indirect word and the 
data must be in the same segment. 


Fault tag modifiers f1, f2, and f3 cause distinct hardware faults whenever 
they are encountered. The modifier f2 is reserved for use in the Multics 
dynamic linking mechanism; the other modifiers result in the signalling of the 
conditions "fault_tag_1" and "fault_tag_3". 


EIS Modifiers 


An EIS modifier appears in the first word of: an EIS multiword instruction. 
It affects the interpretation of operand descriptors in subsequent words of the 
instruction. No check is made by ALM to determine whether the modifier 
specified is consistent with the operand descriptor specified elsewhere. 


An EIS modifier consists of one or more subfields separated by commas. 
Each subfield contains either a keyword as listed below, a register designator, 
or a logical expression. The values of the subfields are OR'ed together to 
produce the result. | | 


‘Keyword Meaning 
“pr Descriptor contains a pointer register reference. 
id Descriptor is an indirect word pointing to the true 
descriptor. 
rl Descriptor length field names a register containing data 
length. 
eparat 


If a separate static object segment is desired, a join pseudo-operation 
specifying static should exist in the program. 
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The pseudo-operations are listed below in alphabetical order. 


ace /string/,expression 

assembles the ASCII string <string> into as many contiguous words as 
are required (up to 42). The delimiting character (/ above) can be 
any non-white-space character. The quoted string can contain newline 
and semicolon characters. The length of the string is placed in the 
first character position in acc format. If present, expression 
defines the length of the string; otherwise, the length is the actual 
length of the quoted string. If the given string is shorter than the 
defined length, it is padded on the right with blanks. 


aci /string/,expression 
is similar to acc, but no length is. stored. The first character 
position contains the first character in aci format. 


arg operand 
assembles exactly like an imatpuceien with a zero opcode. Any form of 
instruction operand can be used. 


bei /string/,expression | 
is similar to aci, but uses GBCD 6-bit character codes and GBCD blanks 
for padding. 


bfs name,expression 
reserves a block of expression words with name defined as the address 
of the first word after the block reserved. 


bool name,expression 
defines the symbol name with the logical value expression. See the 
definition of logical expressions above under "Logical Expressions." 


.bss name,expression 


defines the symbol name as the address of a block of expression words 


at the current location. The name can be omitted, in which case the 
storage is still reserved. : 


call routine(arglist) 
calls out to the procedure routine using the argument list at arglist. 
Both routine and arglist can be any valid instruction operand, 
including tags. If arglist and the parentheses are omitted, an empty 
argument list is created. All registers are saved and restored by 
eall. | 


dec number1l,number2,...,numbern 


assembles the decimal integers number’, number2, through numbern into 
consecutive words. 
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desc4a address(offset) ,length 
desc6a, address(offset),length 
desc9a address(offset),length 


generates one of the operand descriptors of an EIS multiword 
instruction. The address is any arithmetic expression, possibly 
preceded by a pointer register subfield as in an instruction operand. 
The offset is an absolute arithmetic expression giving the offset (in 
characters) to the first bit of data. It can be omitted if the 
parentheses are also omitted. The length is either a built-in index 
register name (al, au, ql, x0, etc.) or an absolute arithmetic 
expression for the data length field of the descriptor. The character 
size (in bits) is specified as part of the pseudo-operation name. 


desc4fl address(offset),length,scale 
desc4ls address(offset),length,scale 
desc4ns address(offset),length,scale 
desc4ts address(offset),length,scale 


generates an operand descriptor for a decimal String. The scale is an 
absolute arithmetic expression for a decimal scaling factor to be 
applied to the operand. It can be omitted, and is ignored in a 
floating-point operand. Data format is specified in the 
pseudo-operation name: desc4fl indicates floating point, desc4ls 
indicates leading sign fixed point, desc4ns indicates unsigned fixed 


point, and desc4ts indicates trailing sign fixed point. Nine-bit | 


digits can be specified by using desc9fl, desc9ls, desc9ns, and 
desc9ts. | 


descb address(offset),length 


eight 


end 


generates an operand descriptor for a bit string. Both offset and 
length are in bits. 


(see the even pseudo-operation) 


terminates the source segment. 


entry namel,name2,...,namen 


generates entry sequences for labels namel, name2, through namen and 
makes the externally-defined symbols name1l, name2, through namen refer 
to the entry sequence code rather than directly to the labels. The 
entry sequence performs such functions as initializing base register 
pr4 to point to the linkage section, which is necessary to make 
external symbolic references (link, segref, explicit links). The 
entry sequence can use (alter) base register pr2, index registers 0 
and 7, and the A and Q registers. It requires pr6 and pr7 to be 
properly set (as they normally are). 


equ name,expression 


even 


2/71 


defines the symbol name with the arithmetic value expression. 


inserts padding (nop) to a specified word boundary. 


firstref extexpression1(extexpression2) 


calls the procedure extexpression! with the argument pointer 
extexpression2 the first time (in a process) that this object segment 
is linked to by an external symbol. If extexpression2 and the 
parentheses are omitted, an empty argument list is supplied. The 
expressions are any external expressions, including tags. 
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getlp 
sets the pointer register pr4 to point to the linkage section. This 
can be used with segdef to simulate the effect of entry. This 
operator can use pointer register pr2, index registers 0 and 7, and 
the A and Q registers, and requires pr6 and pr? to be set properly. 
include segmentname 
inserts the text of the segment segmentname.incl.alm immediately after 
this statement. A standard include library search is done to find the 
include file. See "System Libraries and Search Rules" in Section III 
of the MPM Reference Guide. 


inhibit off 
instruct assembler to turn off the interrupt inhibit bit in subsequent 
instructions. This mode continues until the inhibit on 
pseudo-operation is used. 


inhibit on : 
instructs assembler to turn on the interrupt inhibit bit (bit 28) in 
subsequent instructions. This mode continues until the inhibit off 
pseudo-operation is used. 


itp prno,offset,tag 
generates an ITP pointer referencing the pointer register prno. 


its segno,offset,tag | 
generates an ITS pointer to the segment segno, word offset <offset>, 
with optional modifier tag. If the current location is not even, a 
word of padding (nop) is inserted. Such padding causes any labels on 
the statement to be incorrectly defined. . 


join /text/name1,name2,.../link/name3,name4,.../static/name5,name6,.... 

appends the location counters namel, name2, etc., to the text section, 
appends the location counters name3, name4, etc., to the linkage 
section and appends the location counters name5, name6o, etc., to the 
static section. Any number of names can appear. Each name must have 
been previously referred to in a use statement. Any location counters 
not joined are appended to the text section. If both link and static 
are specified in join pseudo- eperarrones then a warning is printed on 
the terminal. 


link name,extexpression 
defines the symbol name with the value equal to the offset from lp to 
the link pair generated for the external expression extexpression. An 
external expression can include a tag subfield. The name is not an 
external symbol, so an instruction should refer to this link by: 
pr4iname, * 


mod <expression> 
inserts padding (nop) to an Caenneestons word boundary. 


name objectname 


specifies again the object segment name as it appears in the object 
segment. By default, the storage system name is used. 


null 
is ignored. This pseudo-operation is used for comments. 


oct number1,number2d,...,numbern 
is like dec, with octal integer constants. 


odd 
(see the even pseudo-operation) 
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org expression 
sets the location counter to the value of the absolute arithmetic 
expression <expression>. The expression can only use- symbols 
previously defined. | 


push expression 
creates a new stack frame for this procedure, containing expression 
words. If expression is omitted (the usual case), the frame is just 
large enough to contain all cells reserved by temp, tempd, and temp8. 


rem 
" (see the null pseudo-operation) 


return 
is used to return from a procedure that has performed a push. 


segdef namel,name2,...,namen 
makes .the labels name1l, name2, through namen available to the linker 
for referencing from outside programs, using the symbolic names namel, 
namec, through namen. Such incoming references go directly to the 
labels namel, name2 through namey so the segdef pseudo-operation is 
usually used for defining external static data. For program entry 
points, the entry pseudo-operation is usually used. 

segref segname,name1,name2,...,namen 

defines the symbols namel, name2, through namen as external symbols 

referencing the entry points namel, name2, through namen in segment 

segname. This defines a symbol with an. implicit base register 

reference. 


set name,expression 
assigns the arithmetic value expression to the symbol name. Its value 
can be reset in other set statements. 


shortcall routine 
calls out to routine using the argument list pointed to by pr0O. Only 
pr4 and pr6 are preserved by shortcall. 


' shortreturn 


is used to return from a procedure that has not performed a push. 


sixtyfour | 
| (see the even pseudo-operation) 


temp namei(n1),name2(n2),...,namen(nn) | 
defines the symbols namel, name2, through namen to reference unique 
stack temporaries of nl, n2, through nn words each. Fach nis is an 
absolute arithmetic expression and can be omitted (the parentheses 
should also be omitted). The default is one word per namei. 


temp8 name1(n1) ,name2(n2),...,namen(nn) 
is similar to temp, except that 8-word units are allocated, each on an 
8-word boundary. : 


tempd namei(n1),name2(n2),...,namen(nn) 
is similar to temp, except that ni (n2 through nn) double words are 
allocated, each on a double-word boundary. 


use name 
assembles subsequent code into the location counter name. The default 


location counter is ".text."™, 
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vfd T1L1/expression1,T2L2/expression2,...,Tnbn/expressionn 


Zero 


is variable format data. Each expressionj is of type Ti and is stored 
in the next Li bits of storage. As many words are used as required. 
Individual items can cross word boundaries and exceed 36 bits in 
length. Type is indicated by the letters "a" (ASCII constant) or "o" 
(logical expression) or none (arithmetic expression). Regardless of 
type, the low-order Li-bits of data are used, padded if needed on the 
left. The Ti can appear either before or after Li. 


Restrictions: The total length of the variable format data cannot 
exceed 128 words. A relocatable expression cannot be stored ina 
field less than 18 bits long, and it must end on either bit 17 or bit 
35 of a word. 


expressionl,expressione 


assembles expression! into the left 18 bits of a word and expressione 
into the right 18 bits. Both subfields default to zero. 
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Name: alm_abs, aa 


The alm_abs command submits an absentee request to perform ALM assemblies. 
The absentee process for which alm_abs submits a request assembles the segments 
named and dprints and deletes each listing segment if it exists. If the 
-output_file control argument is not specified, an output segment, path.absout, 
is created in the user's working directory. (If more than one path is 
specified, the first is used.) If the segment to be assembled cannot be found, 
no absentee request is submitted. 


Usage 
alm_abs paths {alm_arg} {-dp_args} {-control_args} 


where: 


es paths 
are pathnames of segments to be assembled. 


rede alm_arg 
can be the -list control argument accepted by the alm command 
(described earlier in this document). 


3 dp_args 
can be one or more control arguments (except -delete) accepted by 
the dprint command. (See the MPM Commands for a description of the 
dprint command. ) 


4, control_args 3 
can be one or more of the following control arguments: 


-queue N, -q N 
specifies in which priority queue the request is to be placed 
(N < 3). The default queue is 3. The listing segment is also 
dprinted in queue N. | 


-hold 
specifies that alm_abs should not dprint or delete the listing 
segment. 


-output_file path, -of path 
specifies that absentee output is to go to segment path where path 
is a pathname. 


Notes 


Control arguments and segment pathnames can be mixed freely and can appear 
anywhere on the command line after the command. All control arguments apply to 
all segment pathnames. If an unrecognizable control argument is given, the 
absentee request is not submitted. 


Unpredictable results can occur if two absentee requests are submitted that 
could simultaneously attempt to assemble the same segment or write into the same 
absout segment. 
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When performing several assemblies, it is more efficient to give several 
segment pathnames in one command rather than several commands. With one 
command, only one process is set up. The links that need to be snapped when 
setting up a process and when invoking the assembler need be snapped only once. 
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ame: archive_sort, as 


The archive_sort command is used to sort the components of an archive 
segment. The components are sorted into ascending order by name using the 
Standard ASCII collating sequence. The original archive segment is replaced by 
the sorted archive. For more information on archives and reordering them, see 
the archive command in the MPM Commands and the reorder_archive command in this 
document. 


Usage 
archive_sort paths 


where paths are the pathnames of the archive segments to be sorted. The user 
need not supply the archive suffix. 


Notes 


There may be no more than 1000 components in an archive segment that is to 
be sorted. | 


Storage system errors encountered while attempting to move the temporary 
sorted copy of the archive segment back into the user's original segment result 
in diagnostic messages and preservation of the sorted copy in the user's process 
directory. If the original archive segment is protected, the user is 
interrogated to determine whether it should be overwritten. 
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Name: area_status 


The area_status command is used to display certain information about an 
area. 


Usage 


area_status area_name {-control_args} 


where: 
ee area_name 
is a pathname specifying the segment containing the area to be 
looked at. 
2. control_args 
ean be chosen from the following: 
-trace | | 
displays a trace of all free and u'sed blocks in the area. | 
-offset N, -ofs N 
specifies that the area begins at offset N (octal) in the given 
segment. 
-long, -lg 
dumps the contents of each block in both octal and ASCII format. 


Note 


“If the area has internal format errors, these are reported. The command 
does not report anything about (old) buddy system areas except that the area is 
in an obsolete format. 
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Name: copy_names 


The copy_names command copies all names of one entry (directory, segment, 
multisegment file, or link) to another. All names are left on the original 
entry. The two entries cannot reside in the same directory because name 
duplication is not allowed in the same directory. To move the alternate names 
see the move_names command in this document. 


Usage 


copy_names from_path] {to_pathi ... from_pathn to_pathp} 


where: 


io from_pathi 
is the pathname of the entry whose names are to be copied. 


2. to_pathj 
is the pathname of the entry to which all names on from_pathi are to 
be copied. If this argument is omitted, the working directory is 
assumed. 


Note 


The equal convention may be used. 
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Name: create_area 


The create_area command creates an area and initializes it with 
user-specified area management control information. 


Usage 


create_area virtual_ptr {-control_args} 
where: 


Ace virtual_ptr 
is a virtual pointer to the area to be created. The syntax of 
virtual pointers is described in the cv_ptr_ subroutine description. 
If the segment already exists, the specified portion is still 
initialized as an area. 


Ze control_args 
can be chosen from the following: 


-no_freeing | | 
allows the area management mechanism to use a faster allocation 
strategy that never frees. 


-~dont_free 


is used during debugging to disable the free mechanism. This does 
not affect the allocation strategy. 


-zero_on_alloc 


instructs the area management mechanism to clear blocks at 
allocation time. 


-zero_on_free 


instructs the area management mechanism to clear blocks at free 
time. 


-extend 
causes the area to be extensible, i.e., Span more than one segment. 
This feature should be used only for perprocess, temporary areas. 


-size N 
specifies the octal size, in words, of the area being created or of 
the first component, if extensible. If this control argument is 
omitted, the default size of the area is the maximum size allowable 
for a segment. 


-id STR 
specifies a string to be used in constructing the names of the 
components of extensible areas. 
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Name: delete_external variables 


The delete_external_variables command deletes from the user's name space 
Specified variables managed by the System for the user. All links to those 
variables are unsnapped and their Storage is freed. 


Usage 


delete_external_variables names {-control_arg} 


where: 


Vs names 
are the names of the external variables, separated by spaces, to be 
deleted. 


25 control_arg 
is -unlabeled_common (or -uc) to indicate unlabeled (or blank) 


common. 
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Name: display_component_name, den 


The display_component_name command converts an offset within a _ bound 
segment (e.g., bound_zilch_!23017) into an offset within the referenced 
component object (e.g., comp}1527). This command is especially useful when it 
is necessary to convert an offset within a bound segment (as displayed by a 
stack trace) into an offset corresponding to a compilation listing. 


Usage 
display_component_name path offsets 


where: 


Te path 
is the pathname of a bound object segment. 


2. offsets 


are octal offsets within the text of the bound object segment 
specified by the path argument. 


Example 


The command line: 


display_component_name bound_zilch_ 17523 64251 
might respond with the following lines: 


17523 component5; 1057 
64251 component7 | 63 
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Name: error_table_compiler, ete 


The error_table_compiler command compiles a table of status codes and 
associated messages from symbolic ASCII source segments. The output is in a 
format suitable for the ALM assembler to produce a standard status code table. 


Usage 
error_table_compiler error_table 


where error_table specifies a source segment in the format described below. An 
et suffix is added to the source segment name. The output segment is named 
error_table.alm. . This segment must then be assembled by the ALM assembler prior 
to using it. 


Notes 


Each status code is defined by a statement in the source segment that 
specifies the name, short message, and long message associated with a status 
code. Any number of names may be given to a status code; each name must be 30 
characters or less. Blanks and newline characters in the name are ignored. 
Each name is delimited by a colon (:). 


The short message is eight characters or less in length. Blanks’ and 
newline characters in the short message are ignored. The short message is 
terminated by a comma (,). The short message (but not the terminating comma) 
may be omitted; in this case, the short message is set to the first eight 


characters of the name. 


The long message is 100 characters or less in length. Leading blanks, 
newline characters, and blanks following a newline character are ignored in the 
long message. The long message is terminated by a semicolon (;). Comments that 
begin with the characters /* and end with the characters */ are ignored. 


The syntax of a statement is: 
namej: ... namen: short_message, long _ message; 


An error table source segment is composed of a series of statements of the above 
format, terminated by an end statement. The format of the end statement is: 


end; 
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error_table_compiler error_table_compiler 


There is a special statement that should not be used except when compiling 
the hardcore system error table. This statement causes a special nondynamic 
initialization of status codes in that segment, optimizing the system error 
table slightly. This statement can appear anywhere in the source before the end 
statement. The format of this statement is: 


system; 


See the "List of System Status Codes and Meanings" in Section VII of the 
MPM Reference Guide for a list of system error table status codes. | 


Example 
The comment syntax is similar to PL/I in the following example: 
/* This is a sample error table compiler source segment. */ 
too_few_arguments: toofew,There were eso fee arguments. ; 


could_not_access_data: noprivlg,The user is not sufficiently 
privileged to access required data; 


fatal: disaster: disaster,There was a disastrous error in the data 
base; 


end; 


“Each status code in the table produced by error_table_compiler should be 
referenced as a fixed binary(35) quantity, known externally: 


declare user_errors$disaster fixed bin(35) external, 
code fixed bin(35); 


call data_base_manager (info, code); 
if code = user_errors$disaster /* this is bad */ 
then call kill_subsystem; 
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Name: list_external_variables 


The list_external_variables command prints information about variables 
managed by the system for the user, including FORTRAN common and PL/I external 
Static variables whose names. do not contain dollar’ signs. The default 
information is the location and size of each specified variable. 


Usage 


list_external_variables names {-control_args} 


where: 


1. names 
are names of external variables, separated by Spaces. 


2% control_args 
can be chosen from the following: 


-~unlabeled_common, -uc 
is the name for unlabeled (or blank) common. 


-long, -lg 
prints how and when the variables were allocated. 


-all, -a 
prints information for each variable the system is managing. 


-no_header, -nhe 
Suppresses the header. 
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Name: list_temp_segments 


The list_temp_segments command lists the segments currently in the 
temporary segment pool associated with the user's process. This pool is managed 
by the get_temp_segments_ and release_temp_segments_ subroutines (described in 
the MPM Subroutines). 7 | 


Usage 


list_temp_segments {names} {-control_arg} 


where: 
ts names 
: is alist of names identifying the programs whose temp segments are 

to be listed. 

ae control_arg 
is -all (or -a) to list all temporary segments. If the command is 
issued with no control argument, it lists only those temporary 
segments currently assigned to some program. 

Xample 


To list all the segments currently in the pool, type: 


! list_temp_segments -all 
5 Segments, 2 Free 
!BBBCdfghef fkkkl.temp.0246 work 
!1BBBCdffddfdffkl.temp.0247 work 
!BBBCddffdfffhhh.temp.0253 (free) 


'BBBCdgdgfhfefsf.temp.0254 (free) 
!BBBCvdvfgvdgvvv.temp.0321 editor 


To list the segments currently in use, type: 


! list_temp_segments 
3 Segments 


!BBBCdfghef fkkkl.temp.0246 work 
'BBBCdffddfdffkl.temp.0247 work 
!BBBCvdvfgvdgvvv.temp.03¢c1 editor 
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To list segments used by the program named editor, type: 
! list_temp_segments editor 
1 segment 


{BBBCvdvfgvdgvvv.temp. 0321 editor 
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Name: mbx_add_name, mban 


The mbx_add_name command adds an alternate name to the existing name(s) of 
a mailbox. | 


Usage 


mbx_add_name path names 


where: 

Vs path 
is the pathname of a mailbox. The atar convention is allowed. 

26 names 

re are .names .to be added to a mailbox. The equal convention is 
allowed. 

Notes 


If path does not have the mbx suffix, one is assumed. 


The user must have modify permission on the directory that contains’ the 
entry receiving the additional name(s). 


Two entries in a directory cannot have the same entryname; therefore, 
special action is taken by this command if the added name already exists in the 
specified directory. If the added name is an alternate name of another entry, 
the name is removed from that entry, added to the entry specified by path, and 
the user is informed of this action by a message printed on his terminal. If 
the added name is the only name of another entry, the user is asked if he wishes 
to delete that entry. If he answers "no", no action is taken with respect to 
that name. 


Example 


‘The command line: 
mban >udd>m>Gillis>**.private ==.pv 


adds to every mailbox in >udd>m>Gillis whose name ends in ".private.mbx" a 
similar name ending in ".pv.mbx". | 
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Name: mbx_create, mber 


The mbx_create command creates a mailbox with a specified name in a 
Specified directory. 


Usage 
mbx_create paths 


where paths are the pathnames of mailboxes to be created. 


Notes 
If pathi does not have the mbx suffix, one is assumed. 


| The user must have modify and append permission on the directory in which 
he is creating a mailbox. 


If the creation of a mailbox would introduce a duplication of names’ within 
the directory, and if the old mailbox has only one name, the user is 
interrogated as to whether he wishes the old mailbox to be deleted. If the user 
answers "no", no action is taken. If the old mailbox has multiple names, the 
conflicting name is removed and a message to that effect is issued to the user. 


The extended access placed on a new mailbox is: 


-adros user who created the mailbox 
ao *.SysDaemon. * 
ao al 


For more information on extended access, see the mail command in the MPM 
Commands and mbx_set_acl in this document. | 


Example 


The command line: 
mber Green Jones.home >udd>Multics>Gillis>Gillis 


creates the mailboxes Green.mbx and Jones.home.mbx in the working directory and 
creates the mailbox Gillis.mbx in the directory >udd>Multics>Gillis. 
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Name: mbx_delete, mbdl 


The mbx_delete command deletes the specified mailboxes. 


Usage 
mbx_delete paths 


where paths are the pathnames of mailboxes to be deleted. The star convention : 
is allowed. 


Notes 


If pathi does not have the mbx suffix, one is assumed. 


The user must have modify permission on the containing directory and delete 
extended access on the mailbox. If delete access is lacking, the user is asked 
whether he wants the mailbox deleted. If the user answers "yes", delete access 
is forced. If he answers. "no", no action is taken. 


For more information on extended access, see the mail command in the MPM 
Commands and mbx_set_acl in this document. 


Examples 


~The command line: 
mbdl ** 


deletes all mailboxes in the working directory. 


The command line: 
mbdl Green Dudd>Multics>Gillis>Jones 


deletes the mailbox Green.mbx from the working directory and the mailbox 
Jones.mbx from the directory >udd>Multics>Gillis. 
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Name: mbx_delete_acl, mbda 


The 


mbx_delete_acl command deletes entries from the access control list 


(ACL) of a given mailbox. 


Usage 


mbx_delete_acl path {access_names} 


where: 


Vs path 


is the pathname of a mailbox. The star convention is allowed. 


2. access_names 


Notes 


are access control names of the form Person_id.Project_id.tag. If 
all three components are present, the ACL entry with that name is 
deleted. If one or more components is missing, all ACL entries with 
matching names are deleted. (The matching Strategy is described 
below under "Notes.") If no access control name is specified, the 
user's Person_id and current Project_id are assumed. | 


If path does not have the mbx suffix, one is assumed. 


The user must have modify permission on the containing directory. 


ACL entries for *.SysDaemon.* and *.*.* cannot be deleted. To deny them 
access to a mailbox, set the access to null giving "*.SysDaemon" and "*.*,*" as 
the access_names arguments. 


The matching strategy for access control names is as follows: 


14 


2. 


2/TT 


A literal component name, including "*", matches only a component of 
the same name. 


A missing component name not delimited by a period is taken to be a 
literal "*" (e.g., "*.Multics" is treated as "*.Multics.#*"), Missing 
components on the left must be delimited by periods. 


A missing component name delimited by a period matches any component 
name. 
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Some examples of access_names and which ACL entries they match are: 


ed matches only the ACL entry "*.#,#". 


Multics matches only the ACL entry "Multics.*.*"., (The absence of a 
leading period makes Multics the first component. ) 

-Multics. matches every ACL entry with middle component of Multics. 

= matches every ACL entry. 


matches every ACL entry with a last component of "*". 


uM (null. string) matches every entry ending in ".*.#". 


Example 
The command line: 


mbda Green .Multics Jones 
deletes from the ACL of the mailbox Green.mbx all entries whose name ends in 
" Multics.*" and the specific entry "Jones.*.*". If no ACL entries exist for 
one of the specified access names (e.g., ending in ".Multics.*" from above 
example), an error message is printed. 
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Name: mbx_delete_name, mbdn 


The mbx_delete_name command removes a Specified name from a_e specified 
mailbox. 


Usage 
mbx_delete_name paths 


where paths are the pathnames of mailboxes. The star convention is allowed. 


Notes 


If pathi does not have the mbx suffix, one is assumed. 
The user must have modify permission on the containing directory. 


The entryname portion of pathi is the name to be removed. If removing the 
name would leave no names on the mailbox, the user is asked if he wants the 
mailbox to be deleted. If he answers "no", no action is taken with respect to 
that entryname. 


Example 


The command line: 
mbdn ## private >udd>Multics>Gillis>Jones 
removes from the mailboxes in the working directory all names ending in 


",private.mbx", and removes the name Jones.mbx from the mailbox Jones.mbx in the 
directory >udd>Multics>Gillis. 
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Name: mbx_list_acl, mbla 


The mbx_list_acl command lists all or part of the access control list (ACL) 
of a given mailbox. 


Usage 
mbx_list_acl path {access_names} 


where: 


Vs path | 
is the pathname of a mailbox. The star convention is allowed. 


2. access_names 

| “are access control names of the form Person_id.Project_id.tag. at 
all three components are present, the ACL entry with that name is 
listed. If one or more components is missing, all ACL entries with 
matching names are listed. The matching strategy is described under 
"Notes" in the description of the ' mbx_delete_acl command in this 
document. If no access control name is specified, or if the access 
control name is -all or -a, the entire ACL is listed. 


Note 

If path does not have the mbx suffix, one is assumed. 
Example 

The command line: 


mbla Green *.*.* Jones Gillis... 


lists, from the ACL of Green.mbx, the specific entries "*.*.*" and "Jones. *.*" 
and all entries with a first component of Gillis. If no ACL entry with a first 
component of Gillis exists, an error message is printed. | : 
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Name: mbx_rename, mbrn ww 


The mbx_rename command replaces a given name on a mailbox with a different 
name, without affecting any other names the mailbox has. 


Usage 
mbx_rename pathi1 namel {... pathn namen} 


where: 


Te pathi 
is the pathname of a mailbox. The entryname portion is the name to 
be replaced. The star convention is allowed. 


ae namej 


is the new name to be placed on the mailbox. The equal convention 
is allowed. 


Notes 


If pathi does not have the mbx suffix, one is assumed. 
The user must have modify permission on the directory specified by pathi. 


Since two entries in a directory cannot have the same entryname, special 
action is taken by this command if namei already exists in the directory 
specified by pathi. If the mailbox having the entryname namei has an additional 
name, entryname namei is removed and the user is informed of this action by a 
message printed on his terminal. If the mailbox having the entryname namei has 
only one name, the user is asked if that mailbox is to be deleted. If the user 
answers "no", the renaming operation does not take place. 


Example 


The command line: 
mbrn **,. private ==.public >udd>m>Joe>Normal Urgent 


replaces all mailbox names ending in private.mbx in the working directory with 
Similar names ending in public.mbx and renames the mailbox Normal.mbx in the 
directory >udd>m>Joe to Urgent.mbx. 
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Name: mbx_set_acl, mbsa 


The mbx_set_acl command changes and adds entries to the access control list 
(ACL) of a given mailbox. 


Usage 


mbx_set_acl path model {access_namel ... moden} access_namen 


where: 

Vs path 
is the pathname of a mailbox. The star convention is allowed. 

2% model 
is a valid access mode. It can consist of any or all of the letters 
adros (see "Notes" below) or it can be "n", "null" or "" to specify 
null access. 

36 access_namej] | | 
is an access control name of the form Person_id.Project_id.tag. If 
all three components are present, the ACL entry with that name is 
changed; if no entry with that name exists, one is added. If one or 
more components is missing, all ACL entries with names that match 
the access control name are changed. The matching strategy is 
described under "Notes" in the description of the mbx_delete_acl 
command in this document. If no access control name is_ specified, 
the user's Person_id and current Project_id are assumed. 

Notes 


If path does not have the mbx suffix, one is assumed. 
The user must have modify permission on the containing directory. 


Access on a newly created mailbox is automatically set to adros for the 
user who created it, ao for *.SysDaemon.*, and ao for *.*.*. The extended 
access modes for mailboxes are: 


add a add a message 


delete d delete any message 


read r read any message 
own fe) read or delete only your own messages; that is, those sent by 
you 


status s find out how many messages are in the mailbox 
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Example 


The command line: 


mbsa Green adros Klein.. null Jones.Multics a *.#.* 
manipulates the ACL of Green.mbx so that all previously existing entries with a 
first component of Klein have adros access, Jones.Multics.* has null access’ and 
*.*.* has "a" access. If no ACL entry exists with a first component of Klein, 
an error message is printed. 
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Name: mbx_set_max_length, mbsml 


The mbx_set_max_length command sets the maximum length of a mailbox. The 
mailbox must be empty for this command to work. 


Usage 


mbx_set_max_length path length {-control_args} 
where: 


Is path 


is the pathname of a mailbox. If the suffix mbx is missing, it is 
assumed. The star convention is allowed. 


Ls length 


is the maximum length in words. This number must be greater’ than 
zero. If it is not a multiple of 1024 words, it is rounded to the 
next higher multiple of 1024 with a warning. 


3. control_args | | 
can be chosen from the following list of control arguments: 


-decimal, -dc : 
length is a decimal number. (This is the default.) 


-octal, -oc 
length is an octal number. 


-brief, -bf : 


suppress the warning that length has been rounded to the next higher 
multiple of 1024 words. 
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Name: move_names ww 


The move_names command moves all the alternate names from one entry 
(directory, Segment, multisegment file, or link) to another. The name used to 
designate the entry is not moved. To copy the alternate names, see the 
copy_names command in this document. 


Usage 

move_names from_path1 {to_pathi1 ... from_pathn to_pathn} 
where: 
te from_pathi 


is the pathname of the entry whose alternate names are to be moved. 


2. to_pathi 
is the pathname of the entry to which alternate names on from_pathi 
are to be moved. If to_path is omitted, the working directory is 
assumed. | 


Note 


The equal convention may be used. 
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Name: print_bind_map 


The print_bind_map command displays all or part of the bind map of an 
object segment generated by version number 4 or subsequent versions of the 
binder. 


Usage 


print_bind_map path {components} {-control_args} 


where: 

Vs path 
is the pathname of a bound object segment. 

Ca components 
are the optional names of one or more components of this bound 
object and/or the bindfile name. Only the lines corresponding to 
these components are displayed. A component name must contain one 
Or more mnonnumeric characters. ' If it is purely numerical, it is 
assumed to be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by preceding 
it with the -name control argument (see below). If no component 
names are specified, the entire bind map is displayed. 

3. control_args 


may be chosen from the following list: 


-long, -lg . 
prints the components' relocation values (also printed in the 
default brief mode), compilation times, and source languages. 


-name STR, -nm STR 


is used to indicate that STR is really a component name, even though 
it appears to be an octal offset. 7 , 


-~no_header, -nhe 


omits: all headers, printing only lines concerning the components 
themselves. | 
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Name: print_link_info, pli 


The print_link_info command prints selected items of information for the 
specified object segments. 


Usage 
print_link_info paths {-control_args} 


where: 


Vs paths 
are the pathnames of object segments. 


rate control_args 
can be chosen from the following list. (See "Notes" below. ) 


-length, -ln 3 
print only the lengths of the sections in pathi. 


-entry, -et 
print only a listing of the pathj external definitions, giving their 
symbolic names and their relative addresses within the segment. 


-link, -lk 
print only an alphabetically sorted listing of all the external 
symbols referenced by pathi. 


-long 
prints more information when the header is printed. Additional 
information includes a listing of source programs used to generate 
the object segment, the contents of the "comment" field of the 
Symbol header (often containing compiler options), and any unusual 
values in the symbol header. 


-header, -he | | 
prints the header (The header is not printed by default, if the 
-length, -entry, or -link control argument is specified. ) 


-no_header 
Suppresses printing of the header. 


Note 


Control arguments can appear anywhere on the command line and apply to all 
pathnames. 
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Example 


Also 


print_link_info 


ad 


print_link_info program -long -length 


program 07/30/76 1554.2 edt Fri 


Object Segment >udd>Work>Wilson>program 


Created on 07/30/76 


by Wilson.Work.a 
using Experimental PL/I.Compiler of Thursday, July 26, 1976 at 21:38 


Translator: 

Comment: 

source: ; 
07/30/76 0010.1 
12/15/75 1338.1 
06/30/75 1657.7 
10/06/72 1206.8 
05/18/72 1512.4 
01/17/73 1551.4 

Attributes: 

Object 
Start 0 


Length 11110 


<ready> 


printed is: 


PL 


/I 


0010.1 edt Fri 


map table optimize 


edt 
edt 
edt 
edt 
edt 
edt 


Fri 
Mon 
Mon 
Fri 
Thu 
Wed 


>user_dir_dir>work>Wilson>s>s>program.pl1 
>library_dir_dir>include>linkdcl.incecl.pl1 
>library_dir_dir>include>object_info.incl.pl1 
>library_dir_dir>include>source_map.incl.pl1 
>library_dir_dir>include>symbol_block.incl.pli | 
>library_dir._dir>include>pl1l_symbol_block.inel.plil 


relocatable, procedure, standard 


Text 
0 
3450 


Def's Link Symb Static 
3450 3620 3656 = 3630 
150 36 ~—6h215 0 


Severity, if it is nonzero. 
'Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not e. 
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Name: print_linkage_usage, plu 


The print_linkage_usage command lists the locations and size of linkage and 
static sections allocated for the current ring. This information is useful for 
debugging purposes or for analysis of how a process uses its linkage segments. 


A linkage section is associated with every procedure segment and every data 
segment that has definitions. 


Usage 


print_linkage_usage 


Note 


For standard procedure segments, the information printed includes the name 
of the segment, its segment number, the offset of its linkage section, and the 
size (in words) of both its linkage section and its internal static storage. 
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Name: reorder_archive 


The reorder_archive command provides a convenient way of reordering the 
contents of an archive segment, eliminating the need to extract, order, and 
replace the entire contents of an archive. This command places’ specified 
components at the beginning of the archive, leaving any unspecified components 
in their original order at the end of the archive. For information on archives 
and how they can be sorted, see the archive command in the MPM Commands and the 
archive_sort command in this document. 


Usage 


reorder_archive {-control_argi} path1 ... {-control_argn} pathn 


where: 
1. control_argi 
may be chosen from the following: 
-~console_input, <-ci 
indicates the command is to be driven from terminal input. (This is 
the default. ) 
-file input, -fi 
indicates the command is to be driven from a driving list. (See 
"Notes" below.) 
Zs pathi 
is the pathname of the archive segment to be reordered. If pathi 
does not have the archive suffix, one is assumed. 
Notes 


If no control arguments are specified, the -console_input control argument 
is assumed. 


When the command is invoked with the -console_input control argument or 
with no control arguments, the message “input for archive_name" is printed where 
archive_name is the name of the archive segment to be _ reordered. Component 
names are then typed in the order desired, separated by linefeeds. A period (.) 
on a line by itself terminates input. The two-character line ".*" causes the 
command to print an asterisk (*). This feature can be used to make sure _ there 
are no typing errors before typing a period (.). The two-character line ".q" 
causes the command to terminate without reordering the archive. 


The driving list (-file_input control argument) must have the name 
name.order where name.archive is the name of the archive segment to be 
reordered. The order segment must be in the working directory. It consists of 
a list of component names in the order desired, separated by linefeeds. No 
period (.) is necessary to terminate the list. Any errors in the list (name not 
found in the archive segment, name duplication) cause the command to terminate 
without altering the archive. 
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reorder_archive reorder_archive 
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A temporary segment named ra_temp_.archive is created in the user's process 
directory. This temporary segment is created once per process, and is truncated 
after it is copied into the directory specified by pathi. If the command cannot 
copy the temporary segment, it attempts to save it and rename it with the name 
of the archive specified. 


The reorder_archive command does not operate upon archive segments 
containing more than 1000 components. 
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Name: reset_external_variables 


The reset_external_variables command reinitializes system-managed variables 
to the values they had when they were allocated. | ee: 


Usage 
reset_external_variables names {-control_arg} 


where: 


i names 


are .the names of the external vaneenae separated by spaces, to be 
reinitialized. 


2s control_arg 


is -unlabeled_common (or: -uc) to indicate unlabeled (or block) 
common. : 


Note 


A variable cannot: be reset if the segment containing the initialization 
information is terminated after. the variable is allocated. 
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Name: set_max_length, sml 


The set_max_length command allows the maximum length of a nondirectory 
Segment to be set. The maximum length is the maximum size the segment can 
attain. Currently, maximum length must be a multiple of 1024 words (one page). 


Usage 


set_max_length path length {-control_args} 


where: 

Tes path 
is the pathname of the segment whose maximum length is to be set. 
If path is a link, the maximum length of the target segment of the 
link is set. The star convention can be used. 

ei length 


is the new maximum length expressed in words. If this length is not 
a multiple of 1024 words, it 'is converted to the next higher 
multiple of 1024 words. | 


3. control_args 
can be chosen from the following list of control arguments and can 


appear in any position: 


-decimal, -de 
Says that length is a decimal number. (This is the default.) 


-octal, -oc | 
Says that length is an octal number. 


-brief, -bf | 
Suppresses a warning message that the length argument has been 
converted to the next multiple of 1024 words. 


Notes 


If the new maximum length is less than the current length of the segment, 
the user is asked if the segment should be truncated to the maximum length. If 
the user answers "yes", the truncation takes place and the maximum length of the 
segment is set. If the user answers "no", no action is taken. 


The user must have modify permission on the directory containing the 
segment in order to change its maximum length. 
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Examples 


The command line: 
set_max_length report -oc 10000 


sets the maximum length of the segment named report in the working directory to 
four pages. 


The command line: 
set_max_length # archive 16384 


sets the maximum length of all two-component segments with a second component of 
archive in the working directory to 16 pages. 
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Name: set_ring brackets, srb 


The set_ring_ brackets command allows a user to modify the ring brackets of 
a specified segment. 


Usage 


set_ring_ brackets path {ring numbers} 


where: 

1. path 
is the relative or absolute pathname of the segment whose ring 
brackets are to be modified. 

2% ring numbers 
are the numbers that represent the three ring brackets (rb1 rb2 rb3) 
of the segment. The ring brackets must be in the allowable range 0 
through 7 and must have the ordering: 

rb1 < rb2 < rb3 
If rb1, rb2, and rb3 are omitted, they are set to the user's current 
validation level. 
—rbi 
is the number to be used as the first ring bracket of the segment. 
If rb1 is omitted, rb2 and rb3 cannot be given and rb1, rb2, and rb3 
are set to the user's current validation level. 
rb2 | ; 
is the number to be used as the second ring bracket of the segment. 
If rb2 is omitted, rb3 cannot be given and is set, by default, to 
rbi. 
rb3 

is the number to be used as the third ring bracket of the segment. 
If rb3 is omitted, it is set to rb2. 

Note 


The user's process must have a validation level less than or equal to rbl. 
Ring brackets and validation levels are discussed in "“Intraprocess Access 
Control" in Section VI of the MPM Reference Guide. 
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Name: set_system_storage 


The set_system_storage command establishes an area as the storage region in 
which normal system allocations are performed. 


Usage 
set_system_storage {virtual_ptr -~control_arg}. 


where: 

hg virtual_ptr 
is a virtual pointer to an initialized area. The syntax of virtual 
pointers is described in the cv_ptr_ subroutine description. This 


argument must be specified only if the -system control argument is 
not supplied. 


2s control_arg 
is -system to specify the area used for linkage sections. This 


control argument must be specified only if virtual_ptr is not 
specified. 


Notes 


To initialize or create an area, refer to the description of the 
create_area command. 


-.The area must be set up as either zero_on_free or zero_on_alloc. 


It is recommended that the area specified be extensible. 


Examples 


The command line: 
set_system_storage free_$free_ 


places objects in the segment whose reference name is free_ at the offset whose | 
entry point name is free_. 
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The command line: 

set_system_storage my_seg$ 
uses the segment whose reference name is my_seg. The area is assumed to be at 
an offset of 0O in the segment. The segment must already exist with the 
reference name my_seg and must be initialized as an area. 

The command line: 

set_system_storage my_seg 


uses the segment whose (relative) pathname is my_seg. The segment must already 
exist. : 
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set_user_storage set_user_storage 


Name: set_user_storage 


The set_user_storage command establishes an area as the storage region in 
which normal user allocations are performed. These allocations include FORTRAN 
common blocks and PL/I external variables whose names do not contain dollar 
signs. , 


Usage 


set_user_storage {virtual_ptr -control_arg} 


where: 

hs virtual_ptr 
is a virtual pointer to an initialized area. The syntax of virtual 
pointers is described in the cv_ptr_ subroutine description. This 
argument must be specified only if the -system control argument is 
not specified. ; 

2. control_arg | 7 
is -system to specify the area used for linkage sections. This 
control argument must be specified only if virtual_ptr is not 
specified. | 

Notes 


To initialize or create an area, refer to the description of the 
create_area command. 


“The area must be set up as either zero_on_free or zero_on_alloc. 


It is recommended that the area specified be extensible. 


Examples 


The command line: 
set_user_storage free_$free_ 


places objects in the segment whose reference name is free_ at the offset whose 
entry point name is free_. 
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The command line: 

set_user_storage my_seg$ 
uses the segment whose reference name is my_seg. The area is assumed to be at 
an offset of 0 in the segment. The segment must already exist with the 
reference name my_seg and must be initialized as an area. 

The command line: 

set_user_storage my_seg 


uses the segment whose (relative) pathname is my_seg. The segment must already 
exist. 
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SECTION VII 


SUBROUTINE DESCRIPTIONS 


This section contains descriptions of Multics subroutines, presented in 
alphabetical order. Each description contains the name of the subroutine, 
discusses the purpose of the subroutine, lists the entry points, and describes 
the correct usage for each entry point. Notes and examples are included when 
deemed necessary for clarity. The discussion below briefly describes’ the 
context of the various divisions of the subroutine descriptions. 


ame 


The "Name" heading shows the acceptable name by which the subroutine is 
called. The name is usually followed by a ‘discussion of the purpose and 
function of the subroutine and the results that may be expected from calling it. 


Entry 


Fach "Entry" heading lists an entry point of the subroutine call. This 
heading may or may not appear in a subroutine description; its use is entirely 
dependent upon the purpose and function of the individual subroutine. 


Usage 


This part of the subroutine description first shows the proper format to 
use when mary the subroutine and then explains each element of the call. 
Generally, the format is shown in two parts: a declare statement that gives the 
arguments in PL/I notation and a call line that gives an example of correct 
usage. Each argument of the call line is then explained. Arguments can be 
assumed to be required unless otherwise specified. Arguments that must be 
defined before calling the subroutine are identified as Input; those arguments 


defined by the subroutine are identified as Output. 


Notes 


Comments’ or clarifications that relate to the subroutine as a whole (or to 
an entry point) are given under the "Notes" heading. 
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Other Headings 


Additional headings are used in some descriptions, Particularly the more 
lengthy ones, to introduce Specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 


Status Codes 


The standard status codes returned by the subroutines are further 
identified, when appropriate, as either Storage system or I/0 system. For 
convenience, the most often encountered codes are listed in Appendix B of the 
MPM Subroutines, They are divided into three categories: storage System, I/0 
System, and other. Certain codes have been included in the individual 
Subroutine description if they have a special meaning in the context of that 
Subroutine. The reader should not assume that the code(s) given in a particular 
Subroutine description are the only ones that can be returned. 


Treatment of Links 


Generally, whenever the programmer references a link, the subroutine 
action is performed on the entry pointed to by the link. If this is the case, 
the only way the programmer can have the action performed on the link itself is 
if the subroutine has a chase Switch and he sets the chase switch to QO. 
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Name: active_fne_err_ 


The active_fne_err_ subroutine is called by active functions when they 
detect unusual status conditions. This subroutine formats an error message and 
then signals the condition active_function_error. The default handler for this 
condition prints the error message and then returns the user to command level. 
(See "List of System Conditions and Default Handlers" in Section VI of the MPM 
Reference Guide for further information. ) 


Since this subroutine can be called with a varying number of arguments, it 
is not permissible to include a parameter attribute list in its declaration. 


Usage 


+ 


declare active_fnec_err_ entry options (variable); 


call active_fne_err_ (code, caller, control-string, arg1, ..., argn); 


where: 
1. code is a standard status code (fixed bin(35)). (Input) 
2. caller is the name (char(*)) of the calling procedure. It can be 


either varying or nonvarying. (Input) 

3. control_string is an ioa_ subroutine control string (char(*)). (The ioa_ 
subroutine is described in the MPM Subroutines.) This 
argument is optional. See "Note" below. (Input) 

4, argi are ioa_ subroutine arguments to be substituted into 

| control_string. These arguments are optional. (However, 


they can only be used if the control_string argument is 
given first.) See "Note" below. (Input) 


Note 


The error message prepared by the active_fne_err_ subroutine has the 
format: 


caller: system_message user_message 
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active_fne_err_ 
a a 


where: 


Tg Caller 


2% system_message 


3% user_message 


active_fne_err__ 


is the caller argument described above and should be the 
name of the procedure detecting the error. 


is a standard message from a standard status table 
corresponding to the value of code. If code is equal to 
0, no System_message is returned. 


is constructed by the ioa_ subroutine from the 
control_string and argi arguments described above. If the 
control_string and argi arguments are not’ given, 
user_message is omitted. 
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Name: aim_check_ 


The aim_check_ subroutine determines the relationship between two access 
attributes. An access attribute can be either an authorization or an access 
class. See also the read_allowed_, read_write_allowed_, and write_allowed 
Subroutines in this document. 


Entry: aim_check_$equal 


This entry point compares two access attributes to determine whether they 
Satisfy the equal relationship of the access isolation mechanism (AIM). 


Usage 


declare aim_check_$equal entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); | 


returned_bit = aim_check_$equal (acc_att1, acc_att2); 


where: 
1 ace_atti are access attributes. (Input) 
2. returned_bit is the result of the comparison. (Output) 


"1"b °° acc_attl1 equals acc_att2 
"Ob: ace_att]1 does not equal acc_att2 


Entry: aim_check_$greater 


This entry point compares two access attributes to determine whether they 
Satisfy the greater-than relationship of the AIM. 


Usage 


declare aim_check_$greater entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); 


returned_bit = aim_check_$greater (acc_attl, acc_att2); 


where: 
Ls ace_atti are access attributes. (Input) 
2% returned_bit is the result of the comparison. (Output) 


i a 8 acc_atti1 is greater than acc_att2 
"O"b ace_attl1 iS not greater than acc_att2 
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Entry: aim_check_$greater_or_equal 


This entry point compares two access attributes to determine whether they 
Satisfy either the greater-than or the equal relationships of the AIM. 


Usage 


declare aim_check_$greater_or_equal entry (bit(72) aligned, bit(72) 
aligned) returns (bit(1) aligned); 


returned bit = aim_check_$greater_or_equal (acc_att1, acc_att2); 


where: 
1. acc_atti are access attributes. (Input) 
2 returned_bit is the result of the comparison. (Output) 


LD acc_attl is greater than or equal to ace_att2 
"OND ace_attl is not greater than or equal to acc_att2 
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Name: area_info_ 


The area_info_ subroutine returns information about an area. 


sage 


declare area_info_ entry (ptr, fixed bin (35)); 


call area_info_ (info_ptr, code); 


where; 

1 info_ptr points to the structure described below. (Input) 
25 code is a system status code. (Output) | 

otes | 


The structure pointed to by info_ptr is described by the following PL/I 
declaration: 


del 1 area_info aligned based, 
2 version 7 fixed bin, 
2 control, 
3 extend , bit (1) unaligned, 
3 zero_on_alloc bit (1) unaligned, 
3 zero_on_free bit (1) unaligned, 
3 dont_free bit (1) unaligned, 
3 no_freeing bit (1) unaligned, 
3 system bit (1) unaligned, 
3 mbz bit (30) unaligned, 
2 owner char (32) unaligned, 
2 n_components fixed bin, 
2 size fixed bin (30), 
2 version_of_area fixed bin, 
2 area_ptr ptr, 
2 allocated_blocks fixed bin, 
2 free_blocks fixed bin, 
2 allocated_words fixed bin (30), 
2 free_words fixed bin (30); 
where; 
1. version is set by the caller and should be 1. 
2. control are control bits describing the format and type of the 
area. 
3. extend indicates whether the area is extensible. 
"414th yes | 
woth no 
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4, zero_on_alloc indicates whether blocks are cleared (set to all zeros) at 
allocation time. 
NIMH yes 
"ONh no 


5. zero_on_ free indicates whether blocks are cleared (set to all zeros) at 
free time. 
vase Bal ©, yes 
"OMh no 


6. dont_free indicates whether free requests are disabled (for 
debugging). 
he Li © yes 
"OMh no 


7. no_freeing indicates whether the allocation method assumes no freeing 
will be done. 
"T"b yes 
"O'"b no 

8. system indicates whether the area is managed by the system. 
"1"b yes 
"ONb no 


9. mbz is not used and must be zeros. 


10. owner is the name of the program that created the area if the 
area is extensible. 


_ 11. n_components is the number of components in the area. 
12. size is the total number of words in the area. 


13. version_of_area is O for (old) buddy system areas and 1 for’. standard 
areas. 


14. area_ptr | is filled in by the caller and can point to any component 
| of the area. 


15. allocated_blocks is the number of allocated blocks in the area. 

16. free_blocks is the number of free blocks in the area (not including 
virgin storage within components, i.e., storage after the 
last allocated block). 

17.  allocated_words is the number of allocated words in the area. 

18. free_words is the number of free words in the area not counting 
virgin storage. 


No information is returned about version 0 areas except the version number. 


If the no_freeing bit is on ("1i"b), the counts of free and allocated blocks 
are returned as QO. 


The above structure is defined by the system include file, 


area_info.incl.pll. 
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Name: ascii_to_ebcdic_ 


The ascii_to_ebcdic_ subroutine performs isomor 
O82 i: phic (one-to-one reversible 
conversion from ASCII to EBCDIC. The input data is a String of valid ee 
characters. A valid ASCII character is defined as a 9-bit byte with an octal 
value in the range 0 < octal_value & TTT 2 


Entry: ascii_to_ebedic_ 


This entry point accepts an ASCII character string and generates an EBCDIC 
character string of equal length. _ : 


Usage 


declare ascii_to_ebedic_ entry (char(*), char(#));— 


call ascii_to_ebedic_ (ascii_in, ebcedic_out); 


_ where: 
1. ascii_in is a string of ASCII characters to be converted. (Input) 


Ze ebcdic_out is the EBCDIC equivalent of the input String. (Output) 


Entry: ascii_to_ebedic $table 


This entry point defines the 128-character translation table used to 
perform conversion from ASCII to EBCDIC. The mappings implemented by the 
ascii_to_ebcdic_ and ebcdic_to_ascii_ subroutines are isomorphic; i.e., every 
valid character has a unique mapping, and mappings are reversible. (See the 
ebcdic_to_ascii_ subroutine.) The result of an attempt to convert a character 
that is not in the ASCII character set is undefined. 


Usage 


declare ascii_to_ebcdic_$table char(128) external static; 
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ascii_to_ebcdic_ ascii_to_ebcdic_ 
PHIC A V B 
ASCII EBCDIC 
GRAPHIC OCTAL HEXADECIMAL GRAPHIC 

NUL 000 00 NUL 

SOH 001 01 SOH 

STX 002 02 STX 

ETX 003 03 ETX 

EOT 004 37 EOT 

ENQ 005 2D ENQ 

ACK 006 2E ACK 

BEL 007 2F BEL 

BS 010 16 BS 

HT 011 05 HT 

LF 012 25 NL 

VT 013 ; OB VT 

FF 014 OC NP 

CR 015 OD CR 

SO 016 OE SO 

SI 017 OF SI 

DLE 020 10 DLE 

DC1 021 11 DC1 

DC2 022 12 DC2 

DC3 023 13 ™ 

DC4 024 3C DC4 

NAK 025 3D NAK 

SYN 026 32 SYN 

ETB 027 26 ETB 

CAN 030 18 CAN 

EM 031 19 EM 

SUB 032 3F SUB 

ESC 033 27 ESC 

FS 034 1C IFS 

GS 035 1D IGS 

RS 036 1E IRS 

US 037 1F IUS 

space O40 4O space 
041 SA 

O42 TF " 

# 043 7B # 

$ O44 5B $ 

b O45 6C d 

& O46 50 & 

; O47 7D ' 

( 050 kD ( 

) 051 5D ) 

= 052 5C # 

+ 053 KE + 

’ 054 6B : 

- 055 60 oe 
056 4B ‘ 

/ O57 61 / 

0 060 FO ) 

1 061 F1 1 

2 062 F2 2 

3 063 F3 3 

4 064 Fu mM 
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Oo COA DUI 
© 
Ov 
~ 


4 HK TINK SMES CHNDWA VOSA ZONA UHTMAWAmMvIADroOwWvAI Nwe ee 


‘| 
om 
WW 
~ 


BRrNWOr WR HORA 
a a 
~J 
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bry 
~] 
O COAN NU 


(see "Notes" ) 


wy) 
WW 
“TINK MZSCHNDWOVOSZSOANRUHTADMOAQWPEPOvvit Ave oo 


BD ] (see "Notes" ) 
SF logical NOT 
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ascii to ebcdice ascii_to_ebedic_ 


GRAPHIC OCTAL HEXADECIMAL GRAPHIC 

n 156 95 n 

fe) 157 96 O 

p 160 97 p 

q 161 98 q 

r 162 99 r 

s 163 A2 Ss 

t 164 A3 c 

u 165 AY u 

V 166 A5 V 

W 167 A6 W 

x 170 AT x 

y 171 A8 y 

Zz 172 AQ Z 

{ 173 CO { 

174 uF solid bar 
} 175 ! DO } 

~ 176 Al ~ 

DEL 177 O7 DEL 


Notes 


The graphics ("({" and "]") do not appear in (or map into any graphics that 
appear in) the standard EBCDIC character set. They have been assigned to 
otherwise "illegal" EBCDIC code values in conformance with the bit patterns used 
by the TN text printing train. 


Calling the ascii_to_ebcdic_- subroutine is as efficient as using the PL/I 
translate builtin, since conversion is performed by a single MVT instruction and 
the procedure runs in the stack frame of its caller. 


This mapping differs from the ASCII to EBCDIC mapping discussed in "Punched 
Card Codes" in Section V of the MPM Reference Guide. The characters that differ 
when mapped are: [ ] \ and NL (newline). 
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Name: assign_ 


The assign_ subroutine assigns a specified source value to a specified 
target. Any PL/I arithmetic or String data type can be assigned to any other 
arithmetic or string data type; conversion is done according to the rules of 
PL/I. This subroutine uses rounding in the conversion when the target is 
floating point and truncation in all other cases, 


sage 


declare ea he entry (ptr, fixed bin, fixed bin(35), ptr, fixed bin, fixed 
bin(35)); 


call assign_ (target_ptr, target_type, target_length, source_ptr, 
Ssource_type, source_length) ; 


where: | 

jie target_ptr points to the target of the assignment; it can contain a bit 
offset. (Input) 

2. target_type specifies the type of the target; its value is 2*M+P where M 
is the Multics standard data type code (see "Multics 
Standard Data Type Formats" in Section V of the MPM 
Reference Guide) and P is 0 if the target is unpacked and 1 
if the target is packed. (Input) 

3. target_length is the string length or arithmetic scale and precision of 

the target. If the target is arithmetic, the target_length 

word consists of two adjacent fixed bin(17) unaligned 
fields; the left half of the word is the signed scale and 
the right half of the word is the precision. (Input) 

yu, source_ptr points at the source of the assignment; it can contain a bit 
offset. (Input) 

is source_type specifies the source type using the same format as 
target_type. (Input) 

6. source_length is the string length or arithmetic scale and precision of 


the source using the same format as target_length. (Input) 
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Name: check_star_name_ 


The check_star_name_ subroutine validates an entryname to ensure that it 
has been formed according to the rules for constructing star names. For more 
information on star names, see "Constructing and Interpreting Names" in 
Section I of the MPM Commands. It also returns a nonstandard status code that 
indicates whether the entryname is a star name and whether it is a star name 
that matches every entryname. 


Entry: check_star_name_$path 


This entry point accepts an absolute pathname as its input and validates 
the final entryname in that path. 


Usage 


declare check_star_name_$path entry (char(*), fixed bin(35)); 


call check_star_name_$path (path, code); 


where: 
ie path is the pathname whose final entryname is to be validated. Trailing 
Spaces in the pathname character string are ignored. (Input) 
A code is a status code. (Output) It may have the following values: 
0 | the entryname is valid and is not a estar name 
(does not contain asterisks or question marks). 
1 the entryname is valid and is a star name (does 
contain asterisks or question marks). 
2 | | the entryname is valid and is a star name that 
matches every entryname (either **, or *.**, or 
##  #), , 


error_table_$badstar the entryname is invalid. It violates one or more 
of the rules for constructing star names. 


Entry: - check_star_name_$entry 


This entry point accepts the entryname to be validated as input. 
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check_star_name_ 
a ne ei 


check_star_name_ 
See Fale Bs 


Usage 


declare check_star_name_$entry entry (char(*), fixed bin(35)); 


call check_star_name_$entry (entryname, code); 


where: 

Lis entryname is the entryname to be validated. Trailing spaces in the 
entryname character String are ignored. (Input) 

2. code . is as described above. (Output) 

Notes 


The procedure for obtaining a list of directory entries that match a given 
Star name is explained in the Cescription of the hes_$star_ subroutine in this 
document. 


The procedure comparing an entryname with a given star name is explained in 
the description of the match_star_name_ Subroutine in this document. 
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Name: condition_interpreter_ 


The condition_interpreter_ subroutine can be used by subsystem condition 
handlers to obtain a formatted error message for all conditions except quit, 
alrm, and cput. Some conditions do not have messages and others cause special 
actions to be taken (such as finish). These are described in "Notes" below. 
For more information on conditions, see "Multics Condition Mechanism" in 
Section VI of the MPM Reference Guide. 


Usage 
declare condition_interpreter_ entry (ptr, ptr, fixed bin, fixed bin, ptr, 
char(*), ptr, ptr); 


call condition_interpreter_ (area_ptr, m_ ptr, ming, mode, mc_ptr, 
cond_name, wce_ptr, info_ptr); > 


where: 

1s area_ptr is a pointer to the area in which the message is to be 
allocated, if the message is to be returned. For safety, the 
area size should be at least 300 words. If the message is to 
be printed, the pointer is null. (Input) 

Bae m_ptr points to the allocated message if area_ptr is not null; 
otherwise it is not set. (Output) | 

3% ming is the length (in characters) of the allocated message if 
area_ptr is not null. If area_ptr is null, the length is not 
set. Certain conditions (see "Notes" below) have no messages; 
in these cases, mlng is equal to 0. (Output) 

y, mode is the desired mode of the message to be printed or returned. 
(Input) It can have the following values: 

normal mode 

2 brief mode 
3 long mode 

5:6 mc_ptr if not null, points to machine conditions describing the state 
of the processor at the time the condition was raised. (Input) 

6. cond_name is the name of the condition being raised. (Input) 

‘ < we_ptr is usually null; but when mc_ptr points to machine conditions 
from ring 0, we_ptr points to alternate machine conditions. 
(Input) 

8. info_ptr if not null, points to the information structure described in 


the find_condition_info_ subroutine in this document. (Input) 
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condition_interpreter_ condition_interpreter_ 
eer nee nna ee re eS ner tt a en ee ee ee 
Notes 


The following conditions cause a return with no message: 


command_error 
command_question 
Stringsize 


The finish condition does not usually cause a message to be printed; it 
does, however, cause all I/O blocks to be closed, so that no input/output may be 
done upon return. 
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Name: continue_to_signal_ 


The continue_to_signal_ subroutine enables an on unit that cannot 
completely handle a condition to tell the signalling program, upon its return, 
to search the stack for other on units for the condition. The search continues 
with the stack frame immediately preceding the frame for the block containing 
the on unit. However, if a separate on unit for the any_other condition is 
established in the same block activation as the caller of the 
continue_to_signal_ subroutine, that on unit is invoked before the stack is 
searched further. : 


Usage 


declare continue_to_signal_ entry (fixed bin(35)); 


call continue_to_signal_ (code); 


where code is a standard status code and is nonzero if the signalling 
procedure's frame is not found. (Output) | 


aed 


7-160 | AK92 


ern nese neerreeee-nse nena ree anes aeeeesteheaneersipenatesrnssnsnetanseeunas-aas=- 
; 


convert_aim_ attributes _ 


ee 


convert_aim_attributes_ 
ee a es: 


Name: convert_aim_attributes_ 


The convert_aim_ attributes_ subroutine converts a bit(72) aligned 
representation of an access authorization or access class into a character 
String of the forn: 


Loca btCC.c.€ 


where LL...L is an octal sensitivity level number, and CC...C is an octal string 
representing the access category set. 


This subroutine is generally used by ring 0 auditing programs to format an 
access authorization or class into a character String suitable for logging in 
the syserr log. 


Usage 


declare convert_aim_attributes_ entry (bit(72) aligned, char(32) aligned); 


call convert_aim_ attributes _ (aim_bits, aim_chars); 


where: 
Le aim_bits is the binary representation to be converted. (Input) 


2. ‘aim_chars is the character string representation. (Output) 


Notes 


Only significant digits of the level number (usually a single digit from 0 
to 7) are printed. 


Currently, only 18 access category bits are used, so that only six octal 
digits are required to represent access categories. Therefore, aim_chars is 
padded on the right with blanks, which may be used at a later time for 
additional access information. Trailing zeros are not stripped. 


If either the level or category field of aim_bits is invalid, the erroneous 
field is returned as full octal (6 digits for level, 12 digits for category), 
followed by the string "(undefined)", 
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Name: convert_dial_message 


The convert_dial_message_ subroutine is used in conjunction with the 
dial_manager_ Subroutine to control dialed terminals. It converts an event 
message received from the answering service over a dial control channel into 
Status information more easily used by the user. 


Entry: convert_dial_message_$return_io_module 


This entry point is used to process event messages from the answering 
service regarding the status of an auto call line. In addition to returning 
line status, this entry point also returns the device name and I/O module name 
for use in attaching the line through the iox_ I/O system. 


Usage 
declare convert_dial_message_$return_io_module entry (fixed bin(71), 
char(*), char(*), fixed bin, 1 aligned like status_flags, fixed 
bin(35)); 
call convert_dial_message_$return_io_module (message, channel_name, 
io_module, n_dialed, flags, code); 
where; 
1. message is the event message to be decoded. (Input) 
Cs channel_name is the name of the channel that has dialed-up or  hung-up. 
(Output) 
a io_module is the name of the iox_ I/O module to be used with the 
assigned device. (Output) 
4, n_dialed is the number of terminals currently dialed to the process 
or -1. (Output) 
ar flags is a bit string of the following structure: (Output) 
del 1 flags aligned, 
2 dialed_up bit (1) unal, 
2 hung_up bit (1) unal, 
2 control bit (1) unal, 
2 pad bit: (33) -unals 
on code is a system status code. (Output) 
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Name: convert_status_code_ 


The convert_status_code_ subroutine returns the short and long status 
messages from the standard status table containing the given status code. 


Usage 


declare convert_status_code_ entry (fixed bin(35), char(8) aligned, 
char(100) aligned); 


call convert_status_code_ (code, shortinfo, longinfo); 


where: 
es code is a system status code. (Input) 
a shortinfo is a short status message corresponding to code. (Output) 
De longinfo is a long status message corresponding to code; the message is 
padded on the right with blanks. (Output) 

Note 

If code does not correspond to a valid status code, shortinfo is 
"XXXXXXXX", and longinfo is "Code ddd" where ddd is the decimal representation ww 
of code. 3 ; 

we! 
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Cu 


The cu_ (command utility) subroutine contains a number of useful command 
utility programs that provide functions not directly available in the PL/I 
language. Three of the entry points, cu_$arg_count, cu_$arg_ptr, and cu_$ep, 
are described in the MPM Subroutines; the rest are described below. 


Entry: cu_$ready_proc 


The ready_proc entry point is used to call the current ready procedure of 
the process. It takes an optional argument, which it passes to the ready 
procedure. The ready procedure is automatically invoked by the listener after 
each command line is processed. The ready procedure of the standard command 
environment prints the ready message. 


Usage 


declare cu_$ready_proc entry; 
call cu_$ready_proe (); 
or 


declare cu_$ready_proc entry (1 aligned, 2 bit(1) unaligned, 2 bit(35) 
unaligned); | 


del 1 mode aligned, 
2 ready_sw bit(1) unaligned, 
2 mbz bit(35) unaligned; 


call cu_$ready_proc (mode); 


where: 


1. mode.ready_sw is the static ready switch that specifies whether the ready 
procedure should print a ready message. (Input) 
"I"b print ready message 
"O"b do not print ready message 


2. mode.mbz is reserved for future use and must be "0"b. (Input) 
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Note 


If no argument is given, a static ready switch is passed to the ready 
procedure. The default value of the static ready switch is "1"b. The value of 
the static ready switch can be obtained using the cu_$get_ready_mode entry point 
and changed using the cu_$set_ready_mode entry point (see below). The listener 
invokes the cu_$ready_proec entry point without an argument. The ready_off 
command turns off the static ready switch, the ready_on command turns it on, and 
the ready command calls the cu_$ready_proe entry point with an argument whose 
ready_sw component is "1"b. Thus, if a user-written ready procedure honors’ the 
ready switch, its. printing of the ready message can be controlled by the 
standard ready, ready_on, and ready_off commands. (See the MPM Commands for 
descriptions of the ready, ready_on, and ready_off commands. ) 


Entry: cu_$get_ready_procedure 


This entry point returns the entry value of the current ready procedure of 
the process. 


Usage 


declare cu_$get_ready_procedure entry (entry); 


call cu_$get_ready_procedure (ready_entry); 


where ready_entry is the current ready procedure. (Out put) 


Entry: cu_$set_ready_procedure 


This entry point allows the user to change the ready procedure of his 
process. 


Usage 


declare cu_$set_ready_procedure entry (entry); 


call cu_$set_ready_procedure (ready_entry) ; 


where ready_entry is the (external) procedure entry point that is to become the 
new ready procedure of the process. (Input) 
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Entry: cu_$get_ready_mode 


This entry point returns the value of the static ready mode. 


Usage 


declare cu_$get_ready_mode entry (1 aligned, 2  bit(1) unaligned, 2 
bit(35) unaligned); 


del 1 mode | aligned, 
2 ready_sw bit(1) unaligned, 
2 mbz bit(35) unaligned; 


call cu_$get_ready_mode (mode); 


where: 

ae mode.ready_sw is the current value of the static ready switch. (Output) 
"I"b print ready message 
"O"b do not print ready message 


2% mode.mbz is reserved for future use and must be "0"b. (Output) 


Entry: cu_$set_ready_mode 


This entry point allows the user to change the value of the static ready 
mode. 


Usage 


declare cu_$set_ready_mode entry (1 aligned, 2 bit (1) unaligned, 2 bit(35) 


unaligned) ; 
del 1 mode aligned, 
2 ready_sw bit(1) unaligned, 
2 mbz bit(35) unaligned; 


call cu_$set_ready_mode (mode); 


where: 

lee mode.ready_sw is the new value of the static ready switch. (Input) 
"I"b print ready message , | 
"O"b do not print ready message 

2. mode.mbz is reserved for future use and must be "0O"b. (Input) 
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Entry: cu_$arg_list_ptr 


It is sometimes desirable to design a PL/I procedure to accept a variable 
number of arguments of varying data types (e.g., the ioa_ subroutine described 
in the MPM Subroutines). In these cases, the PL/I procedure must be able to 
interrogate its argument list directly to determine the number, type, and 
location of each argument. The cu_$arg_list_ptr entry point is designed for use 
in such cases and returns a PL/I pointer to its caller's argument list. 


Usage 


declare cu_$arg_list_ptr entry (ptr); 


call cu_$arg_list_ptr (arg_list_ptr); 


where arg_list_ptr is a pointer to the caller's argument list. (Output) 


Note 


A description of the argument list and its structure is found under 
"Argument List Format" in Section II of this document. 


Entry: cu_$arg_ptr_rel 


Some PL/I procedures may need to reference arguments passed to other 
procedures. This entry point permits a procedure to reference arguments in any 
specified argument list. 


Usage 


declare Sante ee PEnareS entry (fixed bin, ptr, fixed bin, fixed bin(35), 
ptr); 


call cu_$arg_ptr_rel (arg_no, arg_ptr, arg_len, code, arg_list_ptr); 


where: 

Vs arg no is an integer specifying the number of the desired argument. 
(Input) 

os arg ptr is a pointer to the unaligned character-string argument 
specified by arg_no. (Output) 

3 arg len is the length (in characters) of the argument specified by 


arg_no. (Output) 
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Cu_ 
4, code is a standard status code. (Output) It can be one of the 
following: 
0 normal return 


error_table_$noarg argument Specified by arg.no does not exist (if 
error_table_$noarg is returned, the values of arg ptr 
and arg_len are undefined) 


oe arg list_ptr is a pointer to the argument list from which this argument 
is being extracted. This pointer can be determined by 
calling cu_$arg list_ptr in the program whose argument list 
is to be processed and then passing it to the program 
requesting reference to the argument list. (Input) | 


Entry: cu_$af_arg count 


This entry point assumes it has been called by an active function. It 
returns to its caller the number of arguments passed to the caller by its 
caller, not including the active function return argument. If the caller. has 
not been invoked as an active function, a standard status code is returned, and, 
if the code is error_table_$not_act_fnce, nargs' is the number of arguments in the 


call (similar to the cu_$arg_count entry point). 


Usage 


declare cu_$af_arg_ count entry (fixed bin, fixed bin(35)); . 


call cu_$af_arg_count (nargs, code); 


where: 
Ls nargs is the number of input arguments passed to the caller. 
(Out put) 
2 code is a standard status code. (Output) It can be one of the 
following: 
0 caller was called as an active function 
error_table_$nodesecr no argument descriptors were passed to _ the 
i | caller or an incorrect argument list header was 
encountered | 


error_table_$not_act_fne the caller was not invoked as an active 
function 


Note 


This entry point and the two following entry points, cu_$af_arg_ ptr and 
cu_$af_return_arg, have been provided so that active functions need not have 
knowledge of the mechanism for returning arguments. 
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Entry: cu_$af_arg_ptr 


This entry point assumes it has been called by an active function. It 
operates in the same fashion as cu_f$arg_ptr, except that it verifies that the 
caller was invoked as an active function, and does not allow the return argument 
to be accessed. That is, if the return argument happens to be the ith argument 
in the actual argument list, and the caller asks cu_$af_arg_ptr for the jth 
argument, it returns the (i+i)st argument (if any). If the (i+1)st argument 
does not exist, a "no argument" standard status code is returned. In practice, 
the return argument is always the last one, but use of this entry and the 
following entry allows the active function to be independent of the position of 
the return argument in the argument list. (See "Note" under cu_$af_arg_ count 
above.) 7 


Usage 


declare cu_$af_arg_ptr entry (fixed bin, ptr, fixed bin, fixed bin(35)); 


call cu_$af_arg_ptr (arg_no, arg_ptr, arg_len, code); 


where: 

a arg no is the number of the desired argument. (Input) 

2. arg ptr is a pointer to the unaligned character-string argument 
specified by arg_no. It is set to the null value if any 
error is encountered. (Output) 

3. arg _len is the length (in characters) of the argument specified by 
arg no. It is set to 0O if any error is encountered. 
(Out put) 

4, code is a standard status code and is the same as for 


cu_$af_arg_count, except that error_table_$noarg can also be 
returned, meaning that the input argument requested by 
arg no was not present. (Output) 


Entry: cu_$af_return_arg 


This entry point assumes it has been called by an active function. It 
makes the active function's return argument available as described in "Note" 
below. It is provided to permit writing of active functions that accept an 
arbitrary number of arguments. (See "Note" under cu_$af_arg_count above.) 
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Usage 


declare cu_$af_return_arg entry (fixed bin, ptr, fixed bin, fixed bin(35)); 
declare return_string char (max_length) varying based (rtn_string ptr); 


Call cu_$af_return_arg (nargs, rtn_string_ ptr, max_length, code); 


where: 

ls nargs is the same as in the cu_$af_arg_ count entry point above. 
(Out put) | 

2. rtn_string_ptr is a pointer to the varying String return argument of the 
active function. (Output) 

Ss max_length is the maximum length of the varying string pointed to by 
rtn_string_ptr. (Output) 

4, code is the same as in the cu_$af_arg_count entry point above. 
(Output) 

Note 


An active function that takes an arbitrary number of arguments uses this 
entry point to return a value. It calls the entry point to get a pointer to the 
return argument and its maximum length. It declares the based varying string, 
return_string, as described above. It then assigns its return value to 
return_string. 


Entry: cu_$stack_frame_ptr 


The cu_$stack_frame_ptr entry point returns a . pointer to its caller's 
stack frame. , 


Usage 


declare cu_$stack_frame_ptr entry (ptr); 


call cu_$stack_frame_ptr (stack_ptr); 


where stack_ptr is a pointer to the caller's stack frame. (Output) 
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Entry: cu_$stack_frame_size 


The cu_$stack_frame_size entry point returns the size (in words) of its 
caller's stack frame. 


Usage 


declare cu_$stack_frame_size entry (fixed bin); 


call cu_$stack_frame_size (size); 


where size is the size (in words) of the caller's stack frame. (Output) 


Entry: cu_$generate_call 


The cu_$generate_call entry point is used to generate a standard call to a 
specified procedure with a specified argument list. This call is designed for 
cases in which a PL/I procedure has explicitly built an argument list from its 
input data. The principal use of this entry is by command processors that call 
a command with an argument list built from a command line input from a terminal. 


Usage 


declare cu_$generate_call entry (entry, ptr); 


call cu_$generate_call (proc_entry, a_ptr); 


where: 

1. proc_entry is the (external) procedure entry point to be called. 
(Input) 

2% a_ptr is a pointer to the argument list to be passed to the called 


procedure. (Input) 
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Entry: cu_$set_command_processor 


Some standard Multics commands (e.g., edm, described in the MPM Commands) 
permit the user to escape from them to execute other commands. In this case, 
the escapable command passes the execute request line to the command processor. 
To allow use of these escapable standard commands in a_ closed subsystem 
environment, instead of calling the command processor directly, the cu_$cp 
(command processor) entry point in cu_is called. (See the MPM Subroutines for 
a description of the cu_$cp entry point.) The latter passes control to the 
procedure entry point defined as the current command processor. The 
cu_$set_command_processor entry point allows a subsystem developer to replace 
the standard command processor with a procedure of his own. This mechanism can 
be used to ensure that the Subsystem remains in full control and still allows 
Subsystem users the use of many standard commands. 


Usage 


declare cu_$set_command_processor entry (entry); 


call cu_$set_command_processor (proc_entry) ; 


where proc_entry is the (external) procedure entry point to which control is 
passed upon receiving a call to cu_$ecp. (Input) 


Entry: cu_$get_command_processor 


This entry point returns to the caller the entry value of the procedure 
currently being invoked in a call to cu_$ep. 


Usage 


declare cu_$get_command_processor entry (entry); 


call cu_$get_command_processor (proc_entry); 


where proc_entry is the procedure entry point to which control is passed upon 
receiving a call to cu_$cp. (Output) 
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Entry: cu_$set_cl_intermediary 


The Multics system provides a_ set of procedures’ to handle any error 
conditions that can be signalled within a process (see the description of the 
signal_ subroutine in. this document). The standard error handlers attempt to 
print an understandable diagnostic and call a procedure to reenter command 
level. Reentering command level is done for a_ user through a call to 
get_to_cl_$unclaimed_signal. However, in order to allow use of the standard 
error handling procedures in a closed subsystem environment, the error handlers 
do not call get_to_cl_$unclaimed_signal directly but call the cu_$cl (command 
level) entry point in cu_. This procedure passes control to the procedure entry 
point currently defined by the last call to cu_$set_cl_intermediary. If 
cu_$set_cl_intermediary has never been called in the process, control is’ passed 
to get_to_cl_$unclaimed_signal on a call to cu_$cl. 


Usage 


declare cu_$set_cl_intermediary entry (entry); 


call cu_$set_cl_intermediary (proc_entry) ; 


where proc_entry is the (external) procedure entry to be called by the standard 
error handlers after printing a diagnostic message. (Input) | 


Entry: cu_$cl 


The cu_$cl entry point is called by all standard error handlers after 
printing a diagnostic message. This entry point passes control to the procedure 
specified by the last call to cu_$set_cl_intermediary. If no such procedure has 
been. specified (the normal  _ case), control is passed to 
get_to_cl_$unclaimed_signal, which reenters command level. 


Usage 


declare cu_$cl entry; 


call cu_$cl (); 


There are no arguments. 
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Entry: cu_$get_cl_intermediary 


This entry point returns to the caller the rocedure entr 
invoked by a call to eu_$el. i y currently being 


Usage 


declare cu_$get_cl_intermediary entry (entry); 
call cu_$get_cl_intermediary (proc_entry); 


where proc_entry is the procedure entry being called by the standard error 
handlers after printing a diagnostic message. (Output) 


Entry: cu_$level_set 


The cu_$level_set entry point is used to change the current protection ring 
validation level. This entry point is useful for procedures that must 
distinguish the periods of time when the procedure is acting in behalf of itself 
(i.e., its own ring) and when it is acting in behalf of another procedure that 
can be in an outer (i.e., less privileged) protection ring. 


Usage 


declare cu_$level_set entry (fixed bin); 
eall cu_$level_set (level); 


where level specifies the new protection validation level and must be greater 
than or equal to the current ring number. (Input) 


H 


Entry: cu_$level_get 


The cu_$level_get entry point is used to obtain the current ring validation 
level. This entry point is normally used prior to a call to cu_$level_set to 
save the current validation level. 
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Usage 


declare cu_$level_get entry (fixed bin); 


call cu_$level_get (level); 


where level is the current validation level. (Out put) 


Entry: cu_$decode_entry_value 


This entry point extracts the pointer components of a PL/I entry value. 


Usage 


declare cu_$decode_entry_value entry (entry, ptr, ptr); 


eall cu_$decode_entry_value (entry_value,' ep_ptr, env_ptr); 


where: 


is entry_value is the entry value to be decoded. (Input) 


2. ep_ptr is the entry point pointer. (Output) 
3. env_ptr is the environment pointer. (Output) 
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Name: cv_bin_ 


The cv_bin_ subroutine converts the binary representation of an integer (of 
any base) to a 12-character ASCII string. 


Usage 


declare cv_bin_ entry (fixed bin, char(12) aligned, fixed bin); 


call ev_bin_ (n, string, base); 


where: 

ie n is the binary integer to be converted. (Input) 

2s string is the ASCII equivaient of n. (Output) 

35 base is the base to use in converting the binary integer (e.g., base 


is 10 for decimal integers). (Input) 


Entry: cv_bin_$dec 


This entry point converts the binary representation of an integer of tase 
10 to a t2-character ASCII string. 


Usage 


declare cv_bin_$dec entry (fixed bin, char(12) aligned); 


call ev_bin_$dec (n, string); 


where: 
is n is the binary integer to be converted. (Input) 
2% string is the ASCII equivalent of n. (Output) 
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ntry: cv_bin_ $oct 


This entry point converts the binary representation of an octal integer ‘oo 
a 1l2-character ASCII string. 


USage 


declare cv_bin_$oct entry (fixed bin, char(12) aligned); 


call ev_bin_$oct (n, string); 


where: 

1. n is the binary integer to be converted. (Input) 
ae string is the ASCII equivalent of n. (Output) 

Note 


If the character-string representation of the number exceeds i2 characters, 
then only the low-order 12 digits are returned. 
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Name: cv_entry_ 


The cv_entry_ subroutine converts a virtual entry to an entry value. A 
virtual entry is a character string representation of an entry value. fThe types 
of virtual entries accepted are described under "Virtual Entries" below. 


Usage 


declare cv_entry_ entry (char(*), ptr, fixed bin(35)) returns (entry); 


entry_value = cv_entry_ (ventry, referencing_ptr, code); 


where: 

1. ventry | is the virtual entry to be converted. (Input) See "Virtual 
Entries" below for more information. 

2. referencing ptr is a pointer to a segment in _ the referencing directory. 
(Input) This directory is searched according to the 
referencing dir search rule to find the entry. A null 
pointer may be given if 'the referencing_dir search rule is 
not to be used. | 

cr code is a standard status code. (Output) 

4, entry_value is the entry value that results from the conversion. 
(Out put) | 

Virtual Entries 


The ev_entry_ subroutine converts virtual entries that contain one or two 
components -- a segment identifier and an optional offset into the segment. 
Altogether, seven forms are accepted. They are shown in the table below. 


In the table that follows, W is an octal word offset from the beginning of 
the segment. It may have a value from 0 to 777777 inclusive. 
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Cv_entry_ 
Virtual 
Entry Interpretation 
_ | 
pathiWw entry at octal word W of segment identified by absolute or 
relative pathname path. 
path} Same as path!/0. 
pathientry_pt entry at word identified by entry point entry_pt in 
segment identified by path. 
path Same as pathilentry path]. 
ref_name$entry_pt entry at word identified by entry point entry_pt in 
segment found via search rules’ whose reference name is 
ref_name. 
ref_name$W entry at octal word W of segment found via search rules 
whose reference name is ref_name. 
ref_name$ Same as ref_name$0. 
Notes 


Use of a pathname in a virtual entry causes the referenced segment to be 
initiated with a reference name equal to its final entryname. Name duplication 
errors occurring during the initiation are resolved by terminating the 
previously-known name. 


The referencing_ptr is used in a call to the hes_$make_entry entry point. 
Refer to the description of this entry point in the MPM Subroutines for more 
information. 


The cv_entry_ subroutine returns an entry value that may be used ina call 
to cu_$generate_call. The cu_$decode_entry_value subroutine may be called if an 
entry pointer is required, rather than an entry variable. For pointers not used 
as entry pointers, use the cv_ptr_ subroutine to convert a virtual pointer. 
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Name: cv_hex_ 


The cv_hex_ subroutine takes an ASCII representation of a hexadecimal 
integer and returns the fixed binary(35) representation of that number. The 
ASCII representation may contain either uppercase or lowercase characters. 


Usage 


declare cv_hex_ entry (char(*)) returns (fixed bin(35)); 


a = cv_hex_ (string); 


where: 
Ts string is the string to be converted. It must be nonvarying. (Input) 
2. a is the result of the conversion. (Output) 


Entry: cv_hex_check_ 


This entry point differs from the ecv_hex_ entry point only in that a code 
is returned indicating the possibility of a conversion error. 


Usage 


‘declare cv_hex_check_ entry (char(*), fixed bin(35)); 
returns (fixed bin(35)); : 


a = cv_hex_check_ (string, code); 


where: 

Ie string is the string to be converted. It must be nonvarying. (Input) 

2% code is a status code that equals 0 if no error occurred; otherwise, 
it is the index of the character that terminated the conversion. 
(Output) | 

3. a is the result of the conversion. (Output) 
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cv _oct_ 


The cv_oct_ subroutine takes an ASCII representation of an octal intege 
and returns the fixed binary(35) representation of that number. it. “Gano 
called as shown because the segment has multiple names. 


Usage 


declare cv_oct_ entry (char(*)) returns (fixed bin(35)); 


a = ev_oct_ (string); 


where; 
1 string is the string to be converted. (Input) 
2% a is the result of the conversion. (Output) 


Entry: ecv_oct_check_ 


This entry point differs from the cv_oct_ entry point only in that a code 
is returned indicating the possibility of a conversion error. It can be called 
as shown because the segment has multiple names. 


Usage 


declare ecv_oct_check_ entry (char(*), fixed bin(35)) returns (fixed 
bin(35)); : 


a = ev_oct_check_ (string, code); 


where: 

ie string is the string to be converted. It must be nonvarying. (Input ) 

es code is a status code that equals 0 if ns error occurr2d,; otherwise 
it is the index of the character that terminated the conversion. 
(Output) 


ce a is the result of the conversion. (Output) 
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Name: cv_ptr_ 


The cv_ptr_ subroutine converts a virtual i i 
—Ptr_ st pointer to a pointer value. A 
virtual pointer is a character string representation of a pointer value. The 
types of virtual pointers accepted are described under "Virtual Pointers" below. 


Usage 


declare cv_ptr_ entry (char(*), fixed bin(35)) returns (ptr); 


ptr_value = cv_ptr_ (vptr, code); 
where: 
Tg vptr is the virtual pointer to be converted. (Input) See 
"Virtual Pointers" below for more information. 
2. code is a standard status code. (Output) 
5% ptr_value is the pointer that results from the conversion. (Out put ) 


Entry: cv_ptr_$terminate 


This entry point is called to terminate the segment that has been initiated 
by a previous call to ecv_ptr_. 


Usage 


declare cv_ptr_$terminate (ptr); 


call ecv_ptr_$terminate (ptr_value); 


where ptr_value is the pointer returned by the previous call to cv_ptr_. 
(Input) 


Notes 


Pointers returned by the cv_ptr_ subroutine cannot be used as_ entry 
pointers in calls to cu_$gen_call or cu_$make_entry_value. The ev_ptr_ 
subroutine constructs the returned pointer to a segment in a way that avoids 
copying of the segment's linkage and internal static data into the combined 
linkage area. The cv_entry_ Subroutine is used to convert virtual entries to an 
entry value. 


The segment pointed to by the returned ptr_value is initiated with a null 
reference name. The cv_ptr_$terminate entry point should be called to terminate 
this null reference name. 
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Virtual Pointers 


The ecv_ptr_ subroutine converts virtual pointers that contain one or two 
components -- a segment identifier and an. optional offset into the segment. 
Altogether, fourteen forms are accepted. They are shown in the table below. 


In the table that follows, W is an octal word offset from the beginning of 
the segment. It may have a value from 0 to 777777 inclusive. B is a decimal 
bit offset within the word. It may have a value from 0 to 35 inclusive. 


Virtual 

Pointer Interpretation 

pathiW(B) points to octal word W, decimal bit B of segment identified 
by absolute or relative pathname path. 

pathiW same as pathiW(0). 

path! same as path;0(0). 

path same as path;0(0). 

pathientry_pt points to word identified by entry point entry_pt in 
segment identified by path. 

ref_namegentry_pt points to word identified. by entry point entry_pt in 
segment whose reference name is ref_name. 

ref_name$W(B) points to octal word W, decimal bit B of segment whose 
reference name is ref_name. 

ref_name$W same as ref_name$W(0). 

ref_name$ same as ref_name$0(0). 

segnoiW(B) points to octal word W, decimal bit B of segment whose 
octal segment number is segno. 

segnoiw same as segnojW(0). 

segno} same as segno}0(0). 

segno same as segno;0(0). 

segnojentry_pt points to word identified by entry point entry_pt in 


segment whose octal segment number is segno. 


A null pointer is represented by the virtual pointer 7777711, by -1i1, or by <1. 
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ame: decode_descriptor_ 


The decode_descriptor_ subroutine extracts information from argument 
descriptors. It should be called by any procedure wishing to handle variable 
length or variable type argument lists. It processes the descriptor format used 
by PL/I and FORTRAN. For a list of the type codes used, see "Argument List 
Format" in Section II of this manual. 


Usage 


declare decode_descriptor_ entry (ptr, fixed bin, fixed bin, bit(1) 
aligned, fixed bin, fixed bin, fixed bin); 


call decode_descriptor_ (ptr, n, type, packed, ndims, size, scale); 


where: 

1. ptr points either directly at the descriptor to be decoded or at 
the argument list in which the descriptor appears. (Input) 

2. n controls which descriptor is decoded. Ifn is O, ptr points at 
the descriptor to be decoded; otherwise, ptr points at the 
argument list header and the nth descriptor is decoded. 
(Input) 

Sx type is the data type specified by the descriptor. Type codes 
appearing in an old form of descriptor are mapped into the new 
codes. (Output) 

QO is returned if an invalid type code is found in the old 
format descriptor 

-~1 is returned if descriptors are not present in the argument 
list or if the nth descriptor does not exist 

4, packed describes how the data is stored. (Output) 
new format descriptors 

AD data is packed 

"O"b data is not packed 
old format descriptors 

"1b data is a string 

"O"b data is not a string 

om ndims indicates either the number of dimensions of the descriptor 
array or whether the descriptor is an array or a scalar. 
(Output) 


new format descriptor 
n descriptor is an array of n dimensions 
0 descriptor is a scalar 


old format descriptor 


1 descriptor is an array 
0 descriptor is a scalar 
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6. size . is the arithmetic precision, string size, or number of 
structure elements of the data of the new format descriptor. 
This value is 0 if an old form of descriptor specifies a 
structure. (Output) 


t% scale is the scale of an arithmetic value for a _ new format 
descriptor. This value is 0 for an old form of descriptor. 
(Output) 
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Name: define_area_ 


The define_area_ subroutine is used to initialize a region of Storage as an 
area and to enable special area management features as well. The region being 
initialized may or may not consist of an entire segment or may not even be 
specified at all, in which case a segment is acquired (from the free pool of 
temporary segments) for the caller. 


Usage 


declare define_area_ entry (ptr, fixed bin (35)); 


call define_area_ (info_ptr, code); 


where: 

1. ‘info_ptr points to the information structure described below. 
(Input) | 3 

2. code is a system status code. (Output) 


The structure pointed to by info_ptr is the standard area_info structure 
used by the various area management routines and is described by the following 
PL/I declaration: 


del 1 area_info aligned based, 
2 version fixed bin, 
2 control, 
3 extend bit (1) unaligned, 
3 zero_on_alloe bit (1) unaligned, 
3 zero_on_free bit (1) unaligned, 
3 dont_free bit (1) unaligned, 
3 no_freeing bit (1) unaligned, 
3 system bit (1) unaligned, 
3 pad bit (30) unaligned, 
2 owner char (32) unaligned, 
2 n_components fixed bin, 
2 size fixed bin (30), 
2 version_of_area fixed bin, 
2 area_ptr ptr, 
é allocated_blocks fixed bin, 
2 free_blocks fixed bin, 
é€ allocated_words fixed bin (30), 
2 free_words fixed bin (30); 
where: — 
1. version is to be filled in by the caller and should be ie 
2. control are control flags for enabling or disabling features of 


the area management mechanism. 
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extend. 


zero _on_alloc 


zero_on_free 


dont_free 


no_freeing 


system 


pad 


owner 


n_components 


size 


version_of_area 


area_ptr 


allocated_blocks 


free_blocks 


define_area_ 
indicates whether the area is extensible. This feature 
should only be used for perprocess, temporary areas. 
14th yes 
"mONhH no 


indicates whether blocks are cleared (set to all zeros) at 
allocation time. 

TL 9) yes 

"Ob no 


indicates whether blocks are cleared (set to all zeros) at 
free time. 
"I" yes 
"O"b no 


indicates whether the free requests are disabled thereby 
not allowing reuse of storage within the area. 

"1b yes 

OD no 


indicates whether the allocation method assumes no free 
requests will ever be made for the area and that, hence, a 
faster allocation strategy can be used. 

Le LD yes 

"O"b no 


is used only by system code and indicates that the area is 
managed by the system. 

"1"b yes 

nONH no 


is not used and must be all zeros. 


is the name of the program requesting that the area be 
defined. This is used for extensible areas only and is 
needed by the temporary segment manager. 


is the number of components in the area. (This item is 
not used by the define_area_ subroutine.) 


is the size, in words, of the area being defined. 


is 1 for current areas and 0 for old-style areas. (This 
item is not used by the define_area_ subroutine.) 


is a pointer to the region to be initialized as an area. 
If this pointer is null, a temporary segment is acquired 
for the area and area_ptr is set as a returned value. If 
area_ptr is initially nonnull, it must point to a 0 mod 2 
address. 


is the number of allocated blocks in the entire area. 
(This item is not used by the define_area_ subroutine.) 


is the number of free blocks in the entire area (not 


counting virgin storage). (This item is not used by the 
define_area_ subroutine.) 
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17. allocated_words is the number of allocated words in the entire area. 
(This item is not used by the define_area_ subroutine.) 


18. free_words is the number of free words in the entire area. (This 
item is not used by the define_area_ subroutine.) 


The above structure is defined by the system include file, 
area_info.incl.pl1. 


See the release_area_ subroutine for a description of how to free up 
segments acquired via this interface. 
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Name: dial_manager __ 


The dial_manager_ subroutine is the user interface to the answering service 
dial facility. The dial facility allows a process to communicate with multiple 
terminals at the same time. For more information, see the description of the 
dial command in the MPM Commands. 


Entry: dial_manager_$allow_dials 


This entry point requests that the answering service allow terminals’ to 
dial Co the calling process. The caller must set 
dial_manager_arg.dial_qualifier to an alphanumeric string from 1 to 22 
characters in length. This string is used by the dial command to differentiate 
multiple processes with the same Person_id and Project_id. The caller must also 
set dial_manager_arg.dial_channel to an event-wait channel in the caller's 
process. The answering service sends notices of dial connections and hangups 
over this channel. After the dial_manager_$allow_dials entry point has been 
called, the event channel may be changed to an event-call channel. The user 
program receiving the wakeup should call the convert_dial_message_ subroutine to 
decode the event message. | 


Usage 


declare dial_manager_$allow_dials entry (ptr, fixed bin(35)); 


call dial_manager_$allow_dials (request_ptr, code); 


where: 

Ve request_ptr. is a pointer to the dial_manager_arg structure described in 
"Notes" below. . (Input) 

ae code is a standard status code. (Output) 


Entry: dial_manager_$dial_out 


This entry point is used to request that an auto call channel be dialed to 
a given telephone number and, if the channel is successfully dialed, that the 
channel be assigned to the requesting process. The caller must set 
dial_manager_arg.dial_qualifier to the telephone number to be dialed. 
Nonnumeric characters in the telephone number are ignored. The caller must also 
set dial_manager_arg.dial_channel to an event-wait channel in his process. The 
answering service sends notice of dial completions and hangups over this 
channel. After the dial_manager_$dial_out entry point has been called the event 
channel may be changed to an event-call channel. The user programs receiving 
the wakeup should call the convert_dial_message_ subroutine to decode the event 
message. The caller may set dial_manager_arg.channel_name to the name of a 
specific channel to be used, or he may set it to null, in which case _ the 
answering service chooses a channel. 
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Usage 


declare dial_manager_$dial_out entry (ptr, fixed bin(35)); 


call dial_manager_$dial_out (request_ptr, code); 


where: 

Le request_ptr is a pointer to the dial_manager_arg structure described 
in "Notes" below. (Input) | 

age code is a standard status code. (Output) 


Entry: dial_manager_$shutoff_dials 


This entry point informs the answering service that the user process wishes 
to prevent further dial connections, and that existing connections should be 
terminated. The same information should be passed to this entry point as was 
passed to the dial_manager_$allow_dials entry point. 


Usage 


declare dial_manager_$shutoff_dials (ptr, fixed bin(35)); 
call dial_manager_$shutoff_dials (request_ptr, code); 


where’ the arguments are the same as for the dial_manager_$allow_dials entry 
point. 


Entry: dial_manager_$privileged_attach 


This entry point allows a privileged process to attach any terminal that is 
in the channel master file, and is not already in use. The effect is as if that 
terminal had dialed to the requesting process. The caller must set all 
variables required by the dial_manager_$allow_dials entry point, and then must 
set dial_manager_arg.channel_name to the name of the channel that is to be 
attached. This must be the same name as specified by the channel master file. 


Usage 


declare dial_manager_$privileged_ attach entry (ptr, fixed bin(35)); 


call dial_manager_$privileged_attach (request_ptr, code); 


where the arguments are the same as for the dial_manager_$allow_dials entry 
point. 
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Entry: dial_manager_$terminate_dial_out 


This entry point is used to request that the answering service hang up an 


auto call line and unassign it from the requesting process. The same 
information should be passed to this entry point as tO the 
dial_manager_$dial_out entry point. The caller must set 


dial_manager_arg.channel_name to the name of the channel being used; 
channel_name cannot be null. 


Usage 


declare dial_manager_$terminate_dial_out entry (ptr, fixed bin(35)); 


call dial_manager_$terminate_dial_out (request_ptr, code); 


where: 

1 request_ptr is a pointer to the dial_manager_arg structure described 
: in "Notes" below. | 

2s code is a standard status code. (Output) 

Notes 


The first argument in all of the calls (request_ptr) is a pointer to the 
dial_manager_arg structure. This structure is used to pass a variety of 
information to the dial_manager_ subroutine. It has the following declaration: 


del 1 dial_manager_arg aligned, 
2 version fixed bin initial (1), 
2 dial_qualifier char(22), a 
2 dial_channel fixed bin(71), 
2 channel_name echar(32); 
where: 
Vs version indicates the version of the structure that is being used. 


Currently this must be 1. 


ae dial_qualifier is the telephone number to be called for calls to. the 
dial_manager_$dial_out entry point. Notice that nonnumeric 
characters are ignored, so the user need not remove them 
from a telephone number string. This is the dial qualifier 
for calls to the dial_manager_$allow_dials entry point. 
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1S an interprocess communication channel used to receive 
messages from the answering service, Notice that the 
channel should be the same for all calls used in the same 
session. 


is used for calls in the dial_manager_$terminate_dial_out 
subroutine to indicate which channel should be 
disconnected. In calls to the dial_manager_$dial_out 
Subroutine, it must be either a null String (in which case 
the answering service attempts to assign any available auto 
call channel) or a Specific channel to be used for the auto 
Call attempt. 
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ame: dprint_ 


The dprint_ Subroutine is the interface for the dprint and dpunch commands 
(described in the MPM Commands). It causes a request to print or punch a 
segment to be added to the specified queue, 


Usage 


declare dprint_ entry (char(*), char(*), ptr, fixed bin(35)); 


Call dprint_ (dir_name, entryname, arg_ptr, code); 


where: 

Ls dir_name is the pathname of the containing directory. (Input) 

2% entryname is the entryname of the segment to be printed or punched. It can 
also be the name of a multisegment file or a link that points to 
a segment or multisegment file. (Input) 

3% arg ptr 1S a pointer to the argument structure described in "Notes" 
below. If no argument structure is Supplied, arg ptr should be 
null. (Input) 

4, code is a status code. (Output) 

Notes 


The dprint_ subroutine uses the structure described below to determine the 
details of the request. If no structure is Supplied, default values are used. 


del 1 dprint_arg based aligned, 

2 version fixed bin, 

2 copies fixed bin, 

2 delete fixed bin, 

2 queue fixed bin, 

2 pt_pech fixed bin, 

2 notify fixed bin, 

2 heading char(64), 

2 output_module fixed bin, 

2 dest char(12), 

2 carriage_control, 
3 nep bit(1) unaligned, 
3 single bit(1) unaligned, 
3 non_edited bit(1) unaligned, 
3 truncate bit(1) unaligned, 
3 ecenter_top_label bit(1) unaligned, 
3 center_bottom_label bit(1) unaligned, 
3 mbz1 bit(30) unaligned, 

2 mbz2(30) fixed bin(35), 

2 forms echar(8), 

2 lmargin fixed bin, 

2 line_lth fixed bin, 
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dprint_ 
2 class 
2 page_lth 
2 top_label 
2 bottom_label 
where: 
1. version 
2. copies 
3. delete 
4, queue 
5. pt —_peh 
6. notify 
7. heading 
8. output_module 


10. 


11. 


dest 


nep 


Single 


dprint_ 


char(8), 

fixed bin, 
char(136), 
char(136); 


is the version number of the structure. The current 
version number is 4 


is the number of copies requested. (The default is 


V3) 


indicates whether the segment is to be deleted after 
printing or punching. 

1 deletes the segment 

0 does not delete the segment (default) 


is the priority queue in which the request is 
placed. (The default is 3.) 


indicates whether the request is for printing or 
punching. 

1 print request (default) 

2 punch request 


indicates whether the requestor is to be notified 
when the request is completed. This feature is not 
implemented at present. 

1 notifies the requestor 

0 does not notify the requestor (default) 


is the string to be used as a heading on the front 
page of the output. If it is a null string, the 
requestor's Person_id is used. (The default is the 
null string.) 


indicates the I/O module to be used in executing the 
request. 


indicates printing (default) 

indicates 7-punching 

indicates Multics card code (mec) punching 
indicates "raw" punching 


FWNh— 


is the string to be used to indicate where the 
output should be delivered. If it is null, the 
requestor's Project_id is used. (The default is the 
null string.) 


indicates whether no-endpage mode is used. 
W4tbh yes 
"Ob no (default) 


indicates whether single mode, which causes all 
vertical tabs: and new pages to be converted to new 
lines, is used. 

41h yes 

"O"b no (default) 
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12. non_edited 


13. truncate 
14. center_top label 


15. center_bottom_label 


16. mbz1 
17. mbz2 
18. forms 


19. Imargin 
20. line_lth 


21. class 
22. -page_lth 


23. top_label 


24. bottom_label 


dprint_ 


indicates whether nonedited mode, which causes all 
nonprinting control characters and non-ASCII 
characters to be printed as octal escape sequences, 
is used. 

14 Mb yes 

"Ob no (default) 

indicates whether truncate mode is used. 

LE 9) yes 

"Ob no (default) 


indicates whether the top label should be’ centered. 


Wap yes 


"OND no (default) 


indicates whether the bottom label Should be 
centered, 

HL yes 

"O'"b no (default) 


is not used and should be set to (30)"0"b. 


is not used and should be set to 0's. 


t 


is not used. 


indicates the left margin position. (The default is 
0.) 


indicates the line length. (The default is -1, 
which implies maximum line length.) 


indicates the request type (formerly called device 
class). (The default is "printer" if pt_pch is 1 
and "punch" if pt_pch is 2.) 


indicates the page length, i.e., the number of lines 
per logical page. (The default is -1, which implies 
the physical page length.) 


is a label to be placed at the top of every page. 
(The default is the null string.) 


is a label to be placed at the bottom of every page. 
(The default is the null string.) 
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Name: ebcdic_to_ascii_ 


The ebcdic_to_ascii_ subroutine performs isomorphic (one-to-one reversible) 
conversion from EBCDIC to ASCII. The input data is a string of valid EBCDIC 
characters. A valid EBCDIC character is defined as a 9-bit byte with a 
hexadecimal value in the range 00 < hex_value < FF (octal value in the range 
000 < oct_value < 377). 


Entry: ebcdic_to_ascii_ 


This entry point accepts an EBCDIC character string and generates an ASCII 
character string of equal length. 


Usage 


declare ebcdic_to_ascii_ entry (char(*), char(*)); 


call ebcdic_to_ascii_ (ebedic_in, ascii_out); 


where: 
ie ebcdic_in is the string of EBCDIC characters to be converted. (Input) 


ae ascii_out is the ASCII equivalent of the input string. (Output) 


Entry: ebcdic_to_ascii_$table 


This entry point defines the 256-character translation table used to 
perform conversion from EBCDIC to ASCII. Of the 256 valid EBCDIC characters, 


only 128 have ASCII equivalents. These latter 128 characters are defined in the 
Isomorphiec ASCII/EBCDIC Conversion Table (in the ascii_to_ebcdic_ subroutine 
description.) For defined characters, the mappings implemented by the 
ebcdic_to_ascii_ and ascii_to_ebedic_ subroutines are isomorphic; i.e., each 
character has a unique mapping, and mappings are reversible. An undefined (but 
valid) EBCDIC character is mapped into the ASCII SUB (substitute) character, 
octal 032; the mapping of such a character is anisomorphic. The result of 
converting an invalid character is undefined. 


Usage 


declare ebcdic_to_ascii_$table char(256) external static; 
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EBCDIC to ASCII conversion cannot be performed by the PL/I translate 
builtin because the EBCDIC string would be scanned under a 77-bit mask. Calling 
the ebcdic_to_ascii_ subroutine is extremely efficient, since conversion is 
performed by a single MVT instruction and the procedure runs in the stack frame 
of its caller. 
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Name: find_condition_info_ 


The find_condition_info_ Subroutine, given a pointer to a stack frame being 
used when a signal occurred, returns information relevant to that condition. 


Usage 


declare find_condition_info_ entry (ptr, ptr, fixed bin(35)); 


call find_condition_info_ (stack_ptr, cond_info_ptr, code); 


where: 


1% Sstack_ptr is a pointer to a stack frame being used when a_e condition 
occurred. It is normally the result of a call to locate the 
condition frame; if null, the most recent condition frame is 
used. (Input) 


2. cond_info_ptr is a pointer to the following structure in which information 
: is returned. (Input) ” 


del 1 cond_info aligned, 
2 me_ptr ptr, 
2 version © fixed bin, 
2 condition_name char(32) varying, 
2 info_ptr ptr, 
2 we_ptr- ptr, 
2 loc_ptr | ptr, 
2 flags aligned, 
3 crawlout — bit(1) unaligned, 
3 mbz1 | bit(35) unaligned, 
2 mbz2 | bit(36) aligned, 
2 user_loc_ptr ptr 
2 mbz(¥) bit(36) aligned; 
where; 
mc_ptr if not null, points to the machine 
conditions. Machine conditions are 
described under "Multics Condition 
Mechanism" in Section VI of the MPM 
Reference Guide. 
version is the version number of this’. structure 
(currently this number is 1). 
condition_name - is the condition name. 
info_ptr points to the info structure if there is 
one; otherwise, it is null. The info 
Structures for various system conditions 
are described in "List of System 
Conditions and Default Handlers" in 


section VI of the MPM Reference Guide. 
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34 


code 


we_ptr 


loc_ptr 


crawlout 


mbz1 


mbz2 


user_loc_ptr 


mbz 


.ind_condition_info_ 


is a pointer to machine conditions 
describing a fault that caused control to 
leave the current ring. This occurs’ when 
the condition described by this structure 
waS Signalled from a lower ring and, 
before the condition occurred, the current 
ring was left because of ae fault. 
Otherwise, it is null. 


is a pointer to the location where the 
condition occurred. If crawlout is "1"b, 
this points to the last location in the 
current ring before the condition 
occurred. 


indicates whether the condition occurred 
in a lower level ring in which it could 
not be adequately handled. 

"NONb no 

"4b yes 


is currently unused and should be set to 
NWOMb .. 
is currently unused and should be set to 
"OND, 


is a pointer to the most recent nonsupport 
location before the condition occurred. 
If the condition occurred in a_ support 
procedure (e.g., a PL/I support routine), 
it is possible to locate the user call 
that preceded the condition. 


is currently unused and should be set to 
NOMND, 


is a standard system status code. It is nonzero when the 
Stack_ptr argument does not point to a condition frame or, 
if the stack_ptr argument is null, when no condition frame 


can be found. 


(Output ) 
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Name: get_default_wdir_ 


The get_default_wdir_ subroutine returns the pathname of the user's current 
default working directory. : 


Usage 


declare get_default_wdir_ entry returns (char(168) aligned); 


default_wdir = get_default_wdir_ ();. 


where default_wdir is the pathname of the user's current default working 
directory. (Output) 
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Name: 


Within an object segment. 


get_definition_ 


get_definition_ 


The get_definition_ subroutine returns a pointer to a specified definition 


Usage 


declare get_definition_ entry (ptr, char(*), char(*), ptr, fixed bin(35)); 


call get_definition_ (def_section_ptr, segname, entryname, def_ptr, code); 


where: 


1. 


2/77 


def_section_ptr 


segname 
entryname 


def_ptr 


code 


is a pointer to the definition section of the object 
segment. This pointer can be obtained via the 
object_info_ subroutine. (Input) 

is the name of the object segment. (Input) 

is the name of the desired entry point. (Input) 


is a pointer to the definition for the entry point. 
(Out put) 


is a standard status’ code. If the entry point is 
found, code is 0. (Output) , 
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Name: get_entry_name_ 


The get_entry_name_ subroutine, given a pointer to an externally defined 
location or entry point in a segment, returns the associated name. 


Usage 
declare get_entry_name_ entry (ptr, char(*), fixed bin(18), char(8) 
aligned, fixed bin(35)); | 


call get_entry_name_ (entry_ptr, symbolname, segno, lang, code); 


where; 
1-3 entry_ptr is a pointer to a procedure entry point. (Input) 


Lo Symbolname is the name corresponding to the location specified by 
entry_ptr. The maximum length is 256 characters. (Output) 


3. segno is the segment number of the object segment where symbolname is 
found. It is useful when entry_ptr does not point to a text 
section. (Output) 


4, lang is the language in which the segment or component pointed to by 
entry_ptr was compiled. (Output) 


5. code is a standard status code. (Output) 
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Name: get_equal_name_ 


The get_equal_name_ subroutine accepts an entryname and an equal name as 
its input and constructs a target name by substituting components or characters 
from the entryname into the equal name, according to the Multics equal 
convention. Refer to "Constructing and Interpreting Names" in Section I of MPM 
Commands for a description of the equal convention and for the rules used_ to 
construct and interpret equal names. 


Usage 


declare get_equal_name_ entry (char(*), char(*), char(32), fixed bin(35)); 


call get_equal_name_ (entryname, equal_name, target_name, code); 


where: 

}e entryname is the entryname from which the target is to be constructed. 
Trailing blanks in the entryname character string are ignored. 
(Input) | 

Qs equal_name is the equal name from which the target is to be constructed. 
Trailing blanks in the equal name character string are ignored. 
(Input) 

oe target_name is the target name that is constructed. (Output) 

4, code is a standard status code. (Output) It can be one of the 
following: 

. Q the target name was constructed properly 


error_table_$bad_equal_name the equal name has a bad format 


error_table_$badequal there is no letter or component in the 
entryname that corresponds to a percent 
character (%) or an equal sign (=) in the 
equal name 


error_table_$longeql the target name to be constructed is longer 
than 32 characters 
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Notes 


If the error_table_$badequal status code is returned, then a target_name is 
returned in which null character Strings are used to represent the missing 
letter or component of entryname. 


If the error_table_$longeql status code is returned, then the first 32 
characters of the target name to be constructed are returned as target_name. 


The entryname argument that is passed to get_equal_name_ can also be used 
as the target_name argument, as long as_ the argument has a length of 32 
characters. 
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Name: get_privileges_ 


The get_privileges_ subroutine returns the access’ privileges of the 
process. (See "Access Control" in Section III of the MPM Reference Guide for 
more information on access privileges.) - 


Usage 


declare get_privileges_ entry returns (bit(36) aligned); 


privilege_string = get_privileges_ (); 


where privilege_string is a bit string with a bit set ("1"b) for each access 
privilege the process has. (Output) 7 


Notes 


The individual bits in privilege string are defined by the following PL/I 
structure: 


del 1 privileges unaligned, 


(2 ipe, 

2 dir, 

2 seg, 

2 soos, 

2 ring1) bit(1), 
2 mbz bit(31); 

where: 

1. ipe indicates whether the access isolation mechanism (AIM) 
restrictions for sending/receiving wakeups to/from any other 
process are bypassed for the calling process. 

"4b yes 
"NONb no 

ex dir indicates whether the AIM- restrictions for accessing any 
directory are bypassed for the calling process. 
WIth yes 
NOMhH no 

3. seg indicates whether the AIM restrictions for accessing any segment 
are bypassed for the calling process. 
ee lil ®, yes 
"O"b no 

4, soos indicates whether the AIM restrictions for accessing directories 


that have been set security-out-of-service are bypassed for the 
calling process. | 

Wath yes 

"ONh no 
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5 ring] 


get_privileges_ 


indicates whether the AIM restrictions for accessing any ring 1 
system segment are bypassed for the calling process. 

I LD 0) yes 

"O"b no 


is unused and must be "O"b, 
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Name: get_ring_ 


The get_ring subroutine returns to the caller the number of the protection 
ring in which the caller is executing. For a discussion of rings see 
"Intraprocess Access Control--Rings" in Section III of the MPM Reference Guide. 


Usage 


declare get_ring_ entry returns (fixed bin(3)); 


ring no = get_ring. (); 


where ring _no is the number of the ring in which the caller is executing. 
(Output) | 
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Name: get_system_free_area_ 


The get_system_free_area_ subroutine returns a pointer to the system free 
area for the ring in which it was called (namely system_free_k_ where k is the 
current ring). Allocations by system programs are performed in this area. 


Usage 


declare get_system_free_area_ entry returns (ptr); 


area_ptr = get_system_free_area_ (); 


where area_ptr points to the system free area. (Output) 
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ame: hes..$add_dir_inacl_entries 


The hes_$add_dir_inacl_entries entry point adds specified directory access 
modes to the initial access control list (initial ACL) for new directories 
created for the specified ring within the specified directory. If an access 
name already appears on the initial ACL of the directory, its mode is changed to 
the one specified by the call. 


Usage 


declare hes_$add_dir_inacl_entries entry (char(*), char(*), ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


call hes_$add_dir_inacl_entries (dir_name, entryname, acl_ptr, acl_count, 
ring, code); 


where: 

Is dir_name is the pathname of the containing directory. (Input) 

es entryname is the entryname of the directory. (Input) 

3. acl_ptr points to a user-filled dir_acl structure. see "Notes" 
| below. (Input) | 

y, acl_count contains the number of initial ACL entries in the dir_acl 

structure. See "Notes" below. (Input). 

5. ring is the ring number of the initial ACL. (Input) 

é. .code is a storage system status code. (Output) 

Notes 


The following structure is used for dir_acl: 


del 1 dir_acl (acl_count) aligned based (acl_ptr), 


2 access_name char(32), 
2 dir_modes | bit(36), 
2 status_code fixed bin(35); 

where: 

1. access_name is the access name (in the form Person_id.Project_id.tag) 
that identifies the processes to which this initial ACL 
entry applies. 

2% dir_modes contains the directory modes for this access. name. The 


first three bits correspond to the modes status, modify, 
and append. The remaining bits must be O's. For example, 
status permission is expressed as "100"b. 
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34 status, code is a storage system status code for this initial ACL entry 
only. | 


If code is returned as error_table_$argerr, then the erroneous initial ACL 
entries in the dir_acl structure have status_code set to an appropriate error 
code. No processing is performed in this instance. 


& 
oy 
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Name: hes_$add_inacl_entries 


The hes_$add_inacl_entries entry point adds specified access modes to the 
initial access control list (initial ACL) for new segments created for the 
specified ring within the specified directory. If an access name already 
appears on the initial ACL of the segment, its mode is changed to the one 
Specified by the call. , | 


~ 


Usage 


declare hes_$add_inacl_entries entry (char(*), char(*), ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


call hes_$add_inacl_entries (dir_name, entryname, acl_ptr, acl_count, ring, 


code); 

where: 

1. dir_name is the pathname of the containing directory. (Input) 

2. entryname is the entryname of the directory. (Input) 

3.  aecl_ptr | points to a user-filled segment_acl structure. see "Notes" 
below. (Input) 

4, acl_count contains the number of initial ACL entries in the segment_acl 
structure. See "Notes" below. (Input) 

5. ring is the ring number of the initial ACL. (Input) 

6. -code is a storage system Status code. (Output) 

Notes 


The following structure is used for segment.acl: 


segment_acl (acl_count aligned based (acl_ptr), 


del 1 
2 access_name 7 — ehar(32), 
2 modes | bit(36), 
2 zero_pad  bit(36), 
2 status_code fixed bin(35); 

where: 

5 access_name is the access name (in the form Person_id.Project_id.tag) that 
identifies the processes to which this initial ACL entry 
applies. 

2. modes contains the modes for this access name. The first three bits 
correspond to the modes read, execute, and write. The 
remaining bits must be O's. For example, rw access is 


expressed as "101"b. 
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3% zero_pad 


4, status_code 


must contain the value zero. (This field is for use with 
extended access and may only be used by the systen.) 


is a storage system status code for this initial ACL entry 
only. 


If code is returned as error_table_$argerr, then the erroneous initial ACL 
entries in segment_acl have status_code set to an appropriate error. code. No 
processing is performed in this instance. 
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Name: hes_.$del_dir_tree 


The hes_$del_dir_tree entry point, given the pathname of a containing 
directory and the entryname of a subdirectory, deletes the contents of the 


Subdirectory from the storage system hierarchy. All segments, links, and 
directories inferior to that subdirectory are deleted, including the contents of 
any inferior directories. The subdirectory is not itself deleted. For 


information on the deletion of directories, see the description of the 
hes_$delentry_file entry point in the MPM Subroutines. 


Usage 


declare hcs.$del_dir_tree entry (char(*), char(#*), fixed bin(35)); 


call hes_$del_dir_tree (dir_name, entryname, code); 


where: 
Des dir_name is the pathname of the containing directory. (Input). 
a entryname is the entryname of the directory. (Input) 


3 code is a storage system status code. (Output) 


tes 


The user must have status and modify permission on the subdirectory and the 
safety switch must be off in that directory. If the user does not have. status 
and modify permission on inferior directories, access is automatically set and 
processing continues. 


If an entry in an inferior directory gives the user access only in a _ pring 
lower than his validation level, that entry is not deleted and no further 
processing is done on the subtree. For information about rings, see 
"Intraprocess Access Control--Rings" in Section III of the MPM Reference Guide. 
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Name: hes_..$delete_dir_inacl_entries 


The hes_$delete_dir_inacl_entries entry point is used to delete specified 
entries from an initial access control list (initial ACL) for new directories 
created for the specified ring within the specified directory. The delete_acl 
structure used by this subroutine is described in the hces_$delete_inacl_entries 
entry point. 


Usage 
declare hecs_$delete_dir_inacl_entries entry (char(*), char(#*), ptr, fixed 
bin, fixed bin(3), fixed bin(35)); 


call hes_$delete_dir_inacl_entries (dir_name, entryname, acl_ptr, 
acl_count, ring, code); 


where: 


1% dir_name is the pathname of the containing directory. (Input). 
es entryname is the entryname of the directory. (Input) 


3. acl_ptr points to the user-filled delete_acl structure as described in 
the hes_$delete_inacl_entries entry point. (Input) 


4, acl. count is the number of initial ACL entries in the delete_acl 
structure. (Input) 


Bic ring is the ring number of the initial ACL. (Input) 
6. -.code is a storage system status code. (Output) 
Notes 


If code is returned as error_table_$argerr, then the erroneous initial ACL 
entries in the delete_acl structure have status_code set to an appropriate error 
code. No processing is performed in this instance. 


If an access_name in the delete_acl structure cannot be matched to _ one 
existing on the initial ACL, then the status_code of that initial ACL entry in 
the delete_acl structure is set to error_table_$user_not_found. Processing 
continues to the end of the delete_acl structure and code is returned as 0. 
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Name: hes_$delete_inacl_ entries 


_The hes_$delete_inacl_entries entry point is called to delete specified 
entries from an initial access control list (initial ACL) for new segments 
created for the specified ring within the specified directory. 


Usage 
declare hes_$delete_inacl_entries entry (char(*), char(#*), ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 
call hes_$delete_inacl_entries (dir_name, entryname, acl_ptr, acl_count, 
ring, code); 
where: 
Ls dir_name is the pathname of the containing directory. (Input) 
2. entryname is the entryname of the directory. (Input) 


i Sis acl_ptr points to the user-filled delete_acl structure. see "Notes" 
below. (Input) 


y, acl_count contains the number of initial ACL entries in the delete_acl 
7 Structure. See "Notes" below. (Input) 


5. ring is the ring number of the initial ACL. (Input) 


6. code is a storage system status code. (Output) 
otes 


The following is the delete_acl structure: 


del 1 delete_acl (acl_count) aligned based (acl_ptr), 
2 access_name char (32), 
2 status_code | fixed bin(35); 
where: 


1s access_name is the access name (in the form of Person_id.Project_id.tag) 
that identifies the initial ACL entry to be deleted. 


ae status_code is a storage system status code for this initial ACL entry 


only. 


If code is returned as error_table_$argerr, then the erroneous initial ACL 
entries in the delete_acl structure have status_code set to an appropriate error 
code. No processing is performed in this instance. 
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If an access_name in the delete_acl structure cannot be matched to one 
existing on the initial ACL, then the status_code of that initial ACL entry in 
the delete_acl structure is set to error_table_$user_not_found. Processing 
continues to the end of the delete_acl structure and code is returned as Q. 
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Name: hces.$get_author 


The hes_$get_author entry point returns the author of a segment, directory, 
multisegment file, or link. 


Usage 


declare hes_$get_author. entry (char(*), char(*), fixed bin(1), char(*), 


fixed 


bin(35)); 


call hes_$get_author (dir_name, entryname, chase, author, code); 


where: 


ie dir_name 


Cu entryname 


3. chase 


4, author 


or code 


Note 


is the pathname of the containing directory. The pathname can 
have a maximum length of 168 characters. (Input) 


is the entryname of the segment, directory, multisegment file, 
or link. It can have a maximum length of 32 characters. 
(Input) 


if entryname refers to a link, this flag indicates whether to 
return the author of the link or the author of the segment, 
directory, or multisegment file to which the link points. 
(Input) 

0 return link author 

1 return segment, directory, or multisegment file author 


is the author of the segment, directory, multisegment file, or 
link in the form of Person_id.Project_id.tag with a maximum 
length of 32 characters. An error is not detected if the 
string, author, is too short to hold the author. (Output) 


is a storage system status code. (Output) 


The user must have status permission on the containing directory. 
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Name: hes_$get_bc_author 


The hes_$get_bc_author entry point returns the bit count author of a 
segment or directory. The bit count author is the name of the user who last set 
the bit count of the segment or directory. 


sage 


declare hes_$get_be_author entry (char(*), char(*), char(*), fixed 
bin(35)); 


call hes_$get_bc_author (dir_name, entryname, bc_author, code); 


where: 

1. dir _name is the pathname of the containing directory. (Input) 

2. entryname is the entryname of the segment or directory. (Input ) 

3. be_author is the bit count author of the segment or directory in the form 
of Person_id.Project_id.tag. An error is not detected if the 
string, bec_author, is too short to hold the bit count author. 
(Output) 

4, code is a storage system status code. (Output) 

Note 


The user must have status permission on the containing directory. 
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Name: hes_$get_dir_ring brackets 


The hes_$get_dir_ring_ brackets entry point, given the pathname of a 
containing directory and the entryname of a subdirectory, returns the value of 
that subdirectory's ring brackets. 


Usage 


declare hes_$get_dir_ring brackets entry (char(*), char(*), (2) fixed 
bin(3), fixed bin(35)); 


call hes_$get_dir_ring brackets (dir_name, entryname, drb, code); 


where; 

1. dir_name is the pathname of the containing directory. (Input) 

Cs entryname is the entryname of the Subdirectory. (Input) 

or drb is a two-element array that contains the directory's ring 
brackets. The first element contains the level required for 
modify and append permission; the second element contains the 
level required for status permission. (Output) 


4, code is a storage system status code. (Output) 


Notes 
_The user must have status permission on the containing directory. 


Ring brackets are discussed in "Intraprocess Access Control--Rings" in 
section III of the MPM Reference Guide. | 
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Name: hes_$get_max_length 


The hes_$get_max_length entry point, given a directory name and entryname, 
returns the maximum length (in words) of the segment. 


Usage 


declare hces_$get_max_length entry (char(*), char(*), fixed bin(19), fixed 
bin(35)); 3 


call hes_$get_max_length (dir_name, entryname, max_length, code); 


where: 

Ts dir_name is the pathname of the containing directory. (Input) 

2% entryname is the entryname of the segment. (Input) 

3% max_length is the maximum length of the segment in words. (Output) 
4, code is a storage system status code. (Output ) | 


Note 


The user must have status permission on the directory containing the 
segment or nonnull access to the segment. 
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ame: hes_$get_max_length_seg 


The hes_$get_max_length_seg entry point, given a pointer to a segment, 
returns the maximum length (in words) of the segment. 


Usage 


declare hes_$get_max_length_seg entry (ptr, fixed bin(19), fixed bin(35)); 


call hes_$get_max_length_seg (seg_ptr, max_length, code); 


where: 


14 seg _ ptr ‘is a pointer to the segment whose maximum length is to be 
| returned. (Input) | 


2. max_length is the maximum length of the segment in words. (Output) 
3. code is a storage system status code. (Output ) 
Note 


The user must have. status permission on the directory containing the 
segment or nonnull access to the segment. 
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Name: hes.$get_ring_brackets 


The hes_$get_ring brackets entry point, given the directory name and 
entryname of a segment, returns the value of that segment's ring brackets. 


Usage 


declare hes_$get_ring_brackets entry (char(*), char(*), (3) fixed bin(3), 
fixed bin(35)); | 


call hes_$get_ring brackets (dir_name, entryname, rb, code); 


where: 

1. dir_name is the pathname of the containing directory. (Input) 

ex entryname is the entryname of the segment. (Input) 

3s rb is a three-element array that contains the segment's ring 
brackets. Ring brackets and validation levels are discussed in 


"Intraprocess Access Control--Rings" in Section III of the MPM 
Reference Guide. (Output) 


4, code is a storage system status code. (Output) 


- The user must have status permission on the containing directory. 
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Name: hes_.$get_safety_sw 


The hes_$get_safety_sw entry point, given a directory name and an 
entryname, returns the value of the Safety switch of a directory or a segment. 


Usage 


declare hes_$get_safety_sw entry (char(*), char(*), bit(1), fixed bin(35)); 


call hes_$get_safety_sw entry (dir_name, entryname, safety_sw, code); 


where: 
ie dir_name is the pathname of the containing directory. (Input) 
2. entryname is the entryname of the directory or segment. (Input) 
3. safety_sw is the value of the sarety switch. (Output). 

"O"b the segment or directory can be deleted 


eb the segment or directory cannot be deleted 


4, code is a storage system status code. (Output) 


Note 


The user must have status permission on the containing directory or must 
have nonnull access to the segment. 


7-66 AK92 


Ae a I AE AAO OOOO AE 
emo a eee © ees meer comme Sine cater—cremnin den AS 


hes_$get_safety_sw_seg | hes_$get_safety_sw_seg 


oe ee ce ee ae ae AS LS NTS SF Se A + AEE oh 
EY SL RD ND oR OY OS SOO RS - 7 . 3 


Name: hes_$get_safety_sw_seg 


The hes_$get_safety_sw_seg entry point, given a pointer to the segment, 
returns the value of the safety switch of a segment. 


Usage 


declare hes _$get_safety_sw_seg entry (ptr, bit(1), fixed bin(35)); 


call hes_$get_safety_sw_seg (seg _ ptr, safety_sw, code); 


where: 

1. seg ptr is a pointer to the segment whose safety switch is to be 
examined. (Input) 

es safety_sw is the value of the segment safety switch. (Output) 
MOD the segment can be deleted 
"1b the segment cannot be deleted 

34 code is a storage system status code. (Output) 

Note 


The user must have status permission on the directory containing the 
segment or must have nonnull access to the segment. 
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Name: hes_$get_search rules 


The hes_$get_search_ rules entry point returns the search rules currently in 
use in the caller's process. 


Usage 


declare hes_$get_search_rules entry (ptr); 


call hes_$zet_search_rules (search_rules_ptr); 


where search _rules_ptr is a pointer to a user-supplied search rules’ structure. 
See "Note" below. (Input) 


Note 
The structure pointed to by search _rules_ptr is declared as follows: 
del 1 search_rules aligned, 
2 number fixed bin, 
2 names (21) char(168) aligned; 
where: 
is number | is the number of search rules in the array. 
ae names are the names of the search rules. They can be absolute 
pathnames of directories or keywords. (See tne 


hes_$initiate_search_rules entry point for a detailed 
description of the search rules.) 
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Name: hes_$get_system_search_rules 


hes_$get_system_search_rules 


The hes_$get_system_search_rules entry point provides the user with the 


directory. 


7-600.1 


values or the site-defined search rule keywords accepted by 
hes_$initiate_search_rules. 
Usage 
declare hces_$get_system_search_rules entry (ptr, fixed bin(35)); 
call hes_$get_system_search_rules (search_rules_ptr, code); 
where: 
mses search_rules_ptr is a pointer to the structure described below. (Input ) 
ap code is a storage system status code. (Output ) 
Notes 
The structure pointed to by search_rules_ptr is declared as follows: 
del 1 drules based aligned, 
2 ntags fixed bin, 
2 nrules fixed bin, 
2 tags (10), 
3 name char(32), 
3 flag bit(36), 
2 rules (10), | 
3 name char(168), 
3 flag bit (36); 
where: 
ie ntags is the number of tags. 
2 nrules is the number of rules. 
3% tags is an array of keywords. 
4, tags.name is the keyword. 
5 tags. flag is a bit field with one bit on. 
6. rules is an array of directory names. 
{ rules.name is the directory absolute path. 
8 rules.flag is a bit field with bits on for every tag that selects this 
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Name: hes_$initiate_search_rules 


The hes_$initiate_search_rules entry point provides the user with a 
subroutine interface for specifying the search rules that he wants to use in his 
process. (For a description of the set_search_rules command, see the MPM 
Commands. ) 


Usage 


declare hes_$initiate_search_rules entry (ptr, fixed bin(35)); 


call hes_$initiate_search_rules (search_rules_ptr, code); 


where: 

1. search_rules_ptr is a pointer to a structure containing the new search 
rules. See "Notes" below. (Input) 

2 code is a storage system status code. (Output) 

Notes 


The structure pointed to by search_rules_ptr is declared as follows: 


del 1 search_rules aligned, 
2 number fixed bin, 
2 names (21) char(168) aligned; 
where: - 
1. number is the number of search rules contained in the array. 


The current maximum number of search rules the user 
can define is 21. 


ae names are the names of the search rules. They can be 
absolute pathnames of directories or keywords. 


Two types of search rules are permitted: absolute pathnames of directories 
to be searched or keywords. The keywords are: 


1. initiated_segments search for the already initiated segments. 

2. ' referencing _dir search the containing directory of the segment 
making the reference. 

oe working dir search the working directory. 

4, process_dir search the process directory. 

Ds home_dir | search the home directory. 
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6. set_search_directories insert the directories following this keyword 
into the default search rules after 


working dir, and make the result the current 
search rules. 


1. Site-defined keywords may also be specified. These keywords may 
expand into one or more directory pathnames. 
The keyword, default, is always defined to be 
the site's default search rules. 


The set_search_directories keyword, when used, must be the first search 
rule specified and the only keyword used. If this keyword is used, 
hes_$initiate_search_rules sets the default search rules, and then inserts the 
specified directories in the search rules after the working directory. 


Some of the keywords, such as set_search_directories, are expanded into 
more than one search rule. The limit of 21 search rules applies to the final 
number of search rules to be used by the process as well as to the number of 
rules contained in the array. 


The search rules remain in effect until this entry point is called with a 
different set of rules or the process is terminated. 


Codes returned from this entry point are: 


error_table_$bad_string (not a pathname or keyword) 
error_table_$notadir 
error_table_$too_many_sr 


Additional codes can be returned from other procedures that are called by 
hes_$initiate_search_rules. | 


For the values of the site-defined keywords, the user may call the 
hes_$get_system_search_rules entry point. 
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Name: hes_$list_dir_inacl 


The hes_$list_dir_inacl entry point is used either to list the entire 
initial access control list (initial ACL) for new directories created for the 
specified ring within the specified directory or to return the access modes for 
specified initial ACL entries. The dir_acl structure described in the 
hes_$add_dir_inacl_entries entry point is used by this entry point. 


Usage 


declare hes_$list_dir_inacl entry (char(*), char(*), ptr, ptr, ptr, fixed 
bin, fixed bin(3), fixed bin(35)); 


call hes_$list_dir_inacl (dir_name, entryname, area_ptr, area_ret_ptr, 
acl_ptr, acl_count, ring, code); 


where: 

1. dir_name is the pathname of the containing directory. (Input) 

2 entryname is the entryname of the directory. (Input) 

3 area_ptr points to an area into which the list of initial ACL entries, 


which makes up the entire initial ACL of the directory, is 

allocated. If area_ptr is null, then the user wants access 

modes for certain initial ACL entries; these will be 

ea by the structure pointed to by acl_ptr (see below). 
Input ) 


4. area_ret_ptr points to the start of the allocated list of initial ACL 
entries. (Output) 


oe acl_ptr if area_ptr is null, then acl_ptr points to an initial ACL 
structure, dir_acl, into which mode information is placed for 
the access names specified in that same structure. (Input) 


6. acl count is oo of entries in the ACL. structure. (Input or 
Output 
Input is the number of entries in the initial ACL structure 
identified by acl_ptr 
Output is the number of entries in the dir_acl structure 
allocated in the area pointed to by area_ptr, if 
area_ptr is not null 


Us ring is the ring number of the initial ACL. (Input) 


8. code is a storage system status code. (Output) 
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If acl_ptr is used to obtain modes for specified access names (rather than 
obtaining modes for all access names on the initial ACL), then each initial ACL 
entry in the dir_acl structure either has status_code set to 0 and contains’ the 
directory's mode or has’ status_code set to error_table_$user_not_found and 
contains a mode of 0. 
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Name: hes_$list_inacl 


The hces_$list_inacl entry point is used either to list the entire initial 
access control list (initial ACL) for new segments created for the specified 
ring within the specified directory or to return the access modes for specified 
initial ACL entries. The segment_acl structure used by this entry point is 
described in the hes_$add_inacl_entries entry point. 


Usage 


declare hes_$list_inacl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


call hes_$list_inacl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, 
acl_count, ring, code); 


where: 
1. dir_name is the pathname of the containing directory. (Input) 
2% entryname is the entryname of the directory. (Input) 
oar area_ptr points to an area into which the list of initial ACL 
entries, which makes up the entire initial ACL of the 
directory, is allocated. If area_ptr is null, then the 
user wants access modes for certain initial ACL entries; 
these will be specified by the structure pointed to by 
acl_ptr (see below). (Input) 
4, area_ret_ptr points to the start of the allocated list of initial ACL 
entries. (Output) 
ae acl_ptr if area_ptr is null, then acl_ptr points to an initial ACL 
structure, segment_acl, into which mode information is to 
be placed for the access names specified in that same 
structure. (Input) 
6. acl_count is the number of entries in the initial ACL structure. 
(Input or Output) 
Input is the number of entries in the initial ACL 
structure identified by acl_ptr 
Output is the number of entries in the segment_acl 
structure allocated in the area pointed to by 
area_ptr, if area_ptr is not null 
1: ring is the ring number of the initial ACL. (Input) 
8. code is a storage system status code. (Output) 
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Note 


If acl_ptr is used to obtain modes for specified access names (rather than 
obtaining modes for all access names on the initial ACL), then each initial ACL 
entry in the segment_acl structure either has status_code set to 0 and contains 
the segment's mode or has status_code set to error_table_$user_not_found and 
contains a mode of 0. 
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Name: hes_$quota_move 


The hecs_$quota_move entry point moves all or part of a quota between two 
directories, one of which is immediately inferior to the other. 


Usage 


declare hes_$quota_move entry (char(#), char(*), fixed bin(18), fixed 
bin(35)); 


call hes_$quota_move (dir_name, entryname, quota_change, code); 


where: 

ie dir_name is the pathname of the containing directory. (Input) 

2 entryname is the entryname of the directory. (Input) 

35 quota_change is the number of records of secondary storage quota to be 
moved between the superior directory and the inferior 
directory. (See "Notes" below.) (Input) 

4, code is a storage system status code. (Output) 

Notes 


The entryname specified by the entryname argument must be a directory. 
The user must have modify permission on both directories. 


After the quota change, the remaining quota in each directory must be 
greater than the number of records used in that directory. 


The quota_change argument can be either a positive or negative number. If 


it is positive, the quota is moved from dir_name to entryname. If it is 
negative, the move is from entryname to dir_name. If the change results in zero 
quota left on entryname, that directory is assumed to no longer contain a 


terminal quota and all of its used records are reflected up to the used records 
on dir_name. It is a restriction that no quota in any of the directories 
Superior to entryname can be modified from a nonzero value to a zero value by 
this subroutine. . 
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Name: hes_$quota_read 


The hes_$quota_read entry point returns’ the segment record quota and 
accounting information for a directory. 


Usage 


declare hes_$quota_read entry (char(*), fixed bin(18 fixed bin(7 


)s i); 
bit(36) aligned, bit(36), fixed bin(1), fixed bin(18), fixed bin(35)); 


call hes_$quota_read (dir_name, quota, trp, tup, sons_lvid tacc_sw, used, 


code); 

where; 

Ts dir_name is the pathname of the directory for which quota information is 
desired. (Input) 

2. quota is the segment record quota in the directory. (Output) 

3 trp is the time-record product (trp) charged to the directory. 
This double-precision number is in units of record-seconds. 
(Output ) 

u, tup is the time, expressed in storage system time format (the 


high-order 36 bits of the 52-bit time returned by the clock_ 
subroutine, described in the MPM Subroutines), that the trp was 
last updated. (Output) 


Dé sons_lvid is the logical volume - ID for segments contained in this 
directory. (Output) 


6. tacc_sw is the terminal account switch. The setting of this switch 
determines how charges are made. (Output) 
weED records are charged against the quota in this directory 
"O"Db records are charged against the quota in the first 
superior directory with a terminal account 


e used ‘is the number of records used by segments in this directory and 
by segments in nonterminal inferior directories. (Output) 

8. code is a storage system status code. (Out put ) 

Note 


If the directory contains a nonterminal account, the quota, trp, and tup 
are all zero. The variable specified by used, however, is kept up-to-date and 
represents the number of records in this directory and inferior, nonterminal 
directories. 
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ame: hes_$replace_dir_inacl 


The hes_$replace_dir_inacl entry point replaces an entire initial access 
control list (initial ACL) for new directories created for the specified ring 
within a specified directory with a user-provided initial ACL, and can 
optionally add an entry for *.SysDaemon.* with mode sma to the new initial ACL. 
The dir_acl structure described in the hes_$add_dir_inacl_entries entry point is 
used by this entry point. 


Usage 


declare hes_$replace_dir_inacl entry (char(*), char(#*), ptr, fixed bin, 
bit(1) aligned, fixed bin(3), fixed bin(35)); 


call hes_$replace_dir_inacl (dir_name, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, ring, code); 


where: 
1. dir_name is the pathname of the containing directory. (Input) 
2. entryname is the entryname of the directory. (Input) 
3. acl_ptr points to a user-supplied dir_acl structure that is to 
replace the current initial ACL. (Input) 
4, acl_count contains the number of entries in the dir_acl_ structure. 
(Input) 
ae no_sysdaemon. sw is a switch that indicates whether the sma *.SysDaemon.* 
| entry is put on the initial ACL after the existing initial 
ACL is deleted and before the user-supplied dir_acl 
entries are added. (Input) 
"O"b adds sma *.SysDaemon.* entry 
"1I"b replaces the ae aat initial ACL with only the 
user-supplied dir_ac 
6. ring is the ring number of the initial ACL. (Input) 
ie code is a storage system status code. (Output) 
Note 


If acl_count is zero, then the existing initial ACL is deleted and only the 
action indicated (if any) by the no_sysdaemon_sw switch is performed. If 
acl_count is greater than zero, processing of the dir_acl entries is performed 
top to bottom, allowing later entries to overwrite previous ones if the 
access_name in the dir_acl structure is identical. | 
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Name: hes_$replace_inacl 


The hes_$replace_inacl entry point replaces an entire initial access 
control list (initial ACL) for new segments created for the specified ring 
within a specified directory with a user-provided initial ACL, and can 
Optionally add an entry for *.SysDaemon.* with mode rw to the new initial ACL. 
The segment_acl structure described in the hes_$add_inacl_entries entry point is 
used by this entry point. | 


Usage 


declare hes_$replace_inacl entry (char(*), char(*), ptr, fixed bin, bit(1), 
fixed bin(3), fixed bin(35)); 


call hes_$replace_inacl (dir_name, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, ring, code); 


where: 

La dir_name is the pathname of the containing directory. (Input) 

2% entryname is the entryname of the directory. (Input) 

ce acl_ptr points to the user-supplied segment_acl structure that is 
to replace the current initial ACL. (Input) 

4, acl_ count contains the number of entries in the segment_acl 
structure. (Input) 

ar no_sysdaemon_sw is a switch that indicates whether the rw *.SysDaemon., # 

' entry is to be put on the initial ACL after the existing 
initial ACL is deleted and before the user-supplied 
Segment_acl entries are added. (Input) 
"O"b adds rw *.SysDaemon.* entry 
"1"b replaces the existing initial ACL with only the 
user-Supplied segment_acl 

6. ring is the ring number of the initial ACL. (Input) 

7. code is a storage system status code. (Output) 

Note 


If'acl_count is zero, then the existing initial ACL is deleted and only the 
action indicated (if any) by the no_sysdaemon_sw switch is performed. If 
acl_count is greater than zero, processing of the segment_acl entries is 
performed top to _ bottom, allowing later entries to overwrite previous ones if 
the access_name in the segment_acl structure is identical. 
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Name: hes_$set_dir_ring brackets 


The hes_$set_dir_ring brackets entry point, given the pathname of the 


containing directory and the entryname of the subdirectory, sets’ the 
Subdirectory's ring brackets. 


sage 


declare hces_$set_dir_ring_ brackets entry (char(*), char(*), (2) fixed 
bin(3), fixed bin(35)); 


call hces_$set_dir_ring_ brackets (dir_name, entryname, drb, code); 


where; 

1. dir_name is the pathname of the containing directory. (Input) 

23 entryname is the entryname of the subdirectory. (Input) 

3 drb is a two-element array specifying the ring brackets of the 
directory. The first element contains the level required for 
modify and append permission; the second element contains the 
level required for status permission. (Input) 

4, code is a storage system status code. (Output) 

Notes: 


The user must have modify permission on the containing directory. Also, 
the validation level must be less than or equal to both the present value of the 
first ring bracket and the new value of the first ring bracket that the user 
wishes set. 


Ring brackets and validation levels are discussed in "Intraprocess Access 
Control--Rings" in the MPM Reference Guide. 
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Name: hes_$set_entry_bound 


The hes_$set_entry_bound entry point, given a directory name and an 
entryname, sets the entry point bound of a segment. 


The entry point bound attribute provides a way Of limiting which locations 
of a segment may be targets of a call. This entry point allows the caller. to 
enable or disable a hardware check of calls toa given segment from other 
Segments. If the mechanism is enabled, all calls to the segment must be made to 
an entry point whose offset is less than the entry point bound. 


In practice, this attribute is most effective when all of the entry points 
are located at the base of the segment. In this case, the entry point bound is 
the number of callable words. 


Usage 


declare i a entry (char(*), char(*), fixed bin(14), fixed 
bin(35)); 


call hes_$set_entry_bound (dir_name, entryname, entry_bound, code); 


where: 

Ts dir_name is the pathname of the containing directory. (Input) 

ae entryname is the entryname of the segment. (Input) 

oe entry_bound is the new value in words for the entry point bound of the 
segment. If the value of entry_bound is 0, then the mechanism 
is disabled. (Input) 


4, code is a storage system status. code. (See "Notes" below. ) 
(Output) 


Notes 
A directory cannot have its entry point bound changed. 
The user must have modify permission on the containing directory. 


If an attempt is made to set the entry point bound of a segment greater 
than the system maximum of 16383, code is set to error_table_$argerr. 


The hes_$set_entry_bound_seg entry point can be used when a pointer to the 
segment is given, rather than a pathname. 
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ame: hes_$set_entry_bound_seg 


The hes_$set_entry_bound_seg entry point, given a pointer to a segment, 
sets the entry point bound of the segment. 


The entry point bound attribute provides a way of limiting which locations 
of a segment may be targets of a call. This entry point allows the caller to 
enable or disable a hardware check of calls to a given segment from other 
segments. If the mechanism is enabled, all calls to the segment must be made to 
an entry point whose offset is less than the entry point bound. 


In practice, this attribute is most effective when all of the entry points 
are located at the base of the segment. In this case, the entry point bound is 
the number of callable words. 


Usage 


declare hces_$set_entry_bound_seg entry (ptr, fixed bin(14), fixed bin(35)); 


call hes_$set_entry_bound_seg (seg _ptr, entry_bound, code); 


where: 

1% seg_ptr is a pointer to the segment whose entry point bound is’ to 
be changed. (Input) 

2s -entry_bound is the new value in words for the entry point bound of the 
segment. If the value of entry_bound is 0, then the 
mechanism is disabled. (Input) 

Ss code is a storage system status’ code. (See "Notes" below.) 
(Output) 

Notes 


A directory cannot have its entry point bound changed. 
The user must have modify permission on the containing directory. 


If an attempt is made to set the entry point bound of a segment to greater 
than the system maximum of 16383, code is set to error_table_$argerr. 


The hces_$set_entry_bound entry point can be used when a pathname of the 
segment is given, rather than a pointer. 
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Name: hes_$set_max_length 


The hes_$set_max_length entry point, given a directory name, sets the 
maximum length (in words) of a segment. 


Usage 


declare ay ene entry (char(*), char(*), fixed bin(19), fixed 
bin(35)); 


call hes_$set_max_length (dir_name, entryname, max_length, code); 


where: 
1. dir_name is the pathname of the containing directory. (Input) — 


2.3 entryname is the entryname of the segment. (Input) 


3% max_length is the new value in words for the maximum length of the 
segment. (Input) 

4, code is a storage system status code. (See "Notes" below. ) 
(Output) 

Notes” 


A directory cannot have its maximum length changed. 
The user must have modify permission on the containing directory. 


The maximum length of a segment is accurate to units of 16 words, and if 
max_length is not a multiple of 16 words, it is set to the next multiple of 16 
words. 


If an attempt is made to set the maximum length of a segment to greater 


thar the system maximun, sys_info$max_seg_ size, code is set to 
error_table_$argerr. The sys_info data base is described in the MPM Reference 
Guide. 


If an attempt is made to set the maximum length of a segment to less’ than 
its current length, code is set to error_table_$invalid_max_length. 


The hes_$set_max_length_seg entry point can be used when the pointer to the 
segment is given, rather than a pathname. 
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Name: hcecs_$set_max_length_seg 


The hes_$set_max_length_seg entry point, given the pointer to the segment, 
sets the maximum length (in words) of a segment. 


Us age 


declare hcs_$set_max_length_seg entry (ptr, fixed bin(19), fixed bin(35)); 


call hes_$set_max_length_seg (seg_ptr, max_length, code); 


where: 

Ws seg ptr is the pointer to the segment whose maximum length is to 
be changed. (Input) ! 

2. max_length is the new value in words for the maximum length of the 
segment. (Input) 

a5 code | is a storage system status’ code. (See "Notes" below.) 
(Output) 

otes 


A directory cannot have its maximum length changed. 
The user must have modify permission on the containing directory. 


The maximum length of a segment is accurate to units of 16 words, and if 
max_length is not a multiple of 16 words, it is set to the next multiple of 16 
words. 


If an attempt is made to. set the maximum length of a segment to greater 


than the system maximun, sys_info$max_seg_ size, code is set to 
error_table_$argerr. The sys_info data base is described in the MPM Reference 
Guide. 


If'an attempt is made to set the maximum length of a segment to less’ than 
its current length, code is set to error_table_$¢invalid_max_length. 3 


The hes_$set_max_length entry point can be used when a pathname of the 
segment is given, rather than the pointer. 
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Name: hes_$set_ring brackets 


The hes_$set_ring brackets entry point, given the directory name _ and 
entryname of a nondirectory Segment, sets the segment's ring brackets. 


Usage 


declare hes_$set_ring_brackets entry (char(*), char(*), (3) fixed bin(3), 
fixed bin(35)); 


call hes_$set_ring_ brackets (dir_name, entryname, rb, code); 


where; 
1. dir_name is the pathname of the containing directory. (Input) 
2% entryname is the entryname of the segment. (Input) 


3. rb is a three-element array specifying the ring brackets of the 
segment; see "Notes" below. (Input) 


4, code is a storage system status code. (Output) 


Notes 
Ring brackets must be ordered as follows: 
rbi<rb2<rb3 


The user must have modify permission on the containing directory. Also, 
the validation level must be less than or equal to both the present value of the 
first ring bracket and the new value of the first ring bracket that the user 
wishes set. 


Ring brackets and validation levels are discussed in "Intraprocess Access 
Control--Rings" in Section III of the MPM Reference Guide. 
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Name: hes_$set_safety_sw 


The hes_$set_safety_sw entry point allows the safety switch associated with 
a segment or directory to be changed. The segment is designated by a directory 
name and an entryname. See "Segment, Directory, and Link Attributes" in Section 
III of the MPM Reference Guide for a description of the safety switch. 


Usage 


declare hces_$set_safety_sw entry (char(*), char(#), bit(1), fixed bin(35)); 


call hes_$set_safety_sw (dir name, entryname, safety_sw, code); 


where: 
1s dir_name is the pathname of the containing directory. (Input) 
2. entryname is the entryname of the segment or directory. (Input) 
3. safety_sw is the new value of the safety switch. (Input) 

OND if the segment can be deleted 

ad fade ©. if the segment cannot be deleted 
q, code is a storage system status code. (Output) 
Notes 


The user must have modify permission on the containing directory. 


The hes_$set_safety_sw_seg entry point can be used when the pointer to the 
segment is given, rather than a pathname. 7 
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Name: hes_$set_safety_sw_seg 


The hes_$set_safety_sw_seg entry point, given a pointer to a segment, sets 
the safety Switch of the segment. See "Segment, Directory, and Link Attributes" 
ee III of the MPM Reference Guide for a description of the safety 
Switch. 


Usage 


declare hces_$set_safety_sw_seg entry (ptr, bit(1), fixed bin(35)); 


call hes_$set_safety_sw_seg (seg ptr, safety_sw, code); 


where: 

Tee seg_ptr is the pointer to the segment. (Input) 

2. safety_sw is the new value of the safety switch. (Input) 
"O"b if the segment can be deleted 
ae fas. if the segment cannot be deleted 


3. code is a storage system status code. (Output) 


Notes 
The user must have modify permission on the containing directory. 


The hes_$set_safety_sw entry point can be used when a pathname of the 
Segment is given, rather than the pointer. 
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Name: hes_$star_ 


The hes_$star_ entry point is the star convention handler for the storage 
system. (See "Constructing and IIInterpreting Names" in Section III of MPM 
Commands.) IIIt is called with a directory name and an entryname that is a star 
name (contains asterisks or question marks). The directory is searched for all 
entries that match the given entryname. Information about these entries is 
returned in a structure. If the entryname is **, information on all entries. in 
the directory is returned. | 3 


status permission is required on the directory to be searched. 


The main entry point returns the storage system type and all names that 
match the given entryname. (See the hes_$star_dir_list_ and hes_$star_list_ 
entry points below to obtain more information about each entry. The 
hes_$star_dir_list_ entry point returns only information kept in the directory 
branch, while the hes_$star_list_ entry point returns information kept in the 
Volume Table of Contents (VTOC). Accessing the VTOC is an additional expense, 
and it can be quite time consuming to access the VTOC entries for all branches 
in a large directory. Further, if the volume is not mounted, it is impossible 
to access the VTOC. Therefore, use of the hes_$star_dir_list_ entry point is 


recommended for all applications in which information from the VTOC is not 
essential.) 


Usage 


declare hes_$star_ entry (char(*), char(*), fixed bin(2), ptr, fixed bin, 
ptr, ptr, fixed bin(35)); 


eall hes_$star_ (dir_name, star_name, select_sw, area_ptr, entry_count, 
entry_ptr, n_ptr, code); 


where: 
TV dir_name is the pathname of the containing directory. (Input) 
2% star_name is the entryname that can contain asterisks or question 
marks. (Input) 
Ss select_sw indicates what information is to be returned. (Input) It 
can be: 
1 information is returned about link entries only 
2 information is returned about segment and directory 
entries only 
3 information is returned about segment, directory, and 
link entries 
4, area_ptr is a pointer to the area in which information is to be 
returned. If the pointer is null, entry_count is set to 
the total number of selected entries. See "Notes" below. 
(Input) = 
oe entry_count is a count of the number of entries that match the 


entryname. (Output) 
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6. entry_ptr is a pointer to the allocated structure in which 


information on each entry is returned. (Output) 


| n_ptr is a pointer to the allocated array of all the entrynames 
in this directory that match star_name. See "Notes" 
below. (Output) | 


8. code is a storage system status code. See "Status Codes" 
below. (Output) 


Even if area_ptr is null, entry_count is set to the total number of entries 
in the directory that match star_name. The setting of select_sw determines 
whether entry_count is the total number of link entries, the total number of 
segment and directory entries, or the total number of all entries. 


If area_ptr is not null, the entry information structure and the name array 
are allocated in the user-supplied area. . : 


The entry information structure is as follows: 


del 1 entries (ecount) aligned based (entry_ptr), 
(2 type bit(2), 
2 nnames fixed bin(15), 
2 nindex fixed bin(17)) unaligned; 
where: 
1. type specifies the storage system type of entry: 


0 ("00"b) link 
1 ("01"b) segment 
2 ("10"b) directory 


2. nnames specifies the number of names for this entry that match 
star_name. 


3% nindex ' specifies the offset in the array of names (pointed to by 
n_ptr) for the first name returned for this entry. 


All of the names that are returned for any one entry are_ stored 
consecutively in an array of all the names allocated in the user-supplied area. 
The first name for any one entry begins at the nindex offset in the array. 


The names array, allocated in the user-supplied area, is as follows: 
declare names (total_names) char(32) aligned based (n_ptr); 


where total_names is the total number of names returned. 
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The user must provide an area large enough for the hes_$star_ entry point 
to store the requested information. 


! 


Entry: hes_$star_dir_list_ 


This entry point returns information about the selected entries, such as 
the mode and bit count for branches, and link pathnames for links. It returns 
only information kept in directory branches, and does not access the VTOC 
entries for branches. This entry point is more efficient than the 
hes_$star_list_ entry point. 


Usage 
declare hes_$star_dir_list_ entry (char(*), char(*), fixed bin(3), ptr, 
fixed bin, fixed bin, ptr, ptr, fixed bin(35)); 
call hes_$star_dir_list_ (dir_name, star_name, select_sw, area_ptr, 


branch_count, link_count, entry_ptr, n_ptr, code); 


where the arguments are exactly the same as those for the hes_$star_list_ entry 
point below. 


Notes 
The notes for hes_$star_list_ also apply to this entry. 


The layouts of these structures are identical to those used by 
hes_$star_list_. Only the meanings of two elements differ: dtem and bit_count. 


del 1 branches (count) aligned based (entry_ptr), 

(2 type bitC2),. . 

2 nnames . fixed bin(15), 

2 nindex fixed bin(17), 

2 dtem bit(36), 

2 padi bit(36), 

2 mode DLE C5), 

2 raw_mode bit(5), 

2 master_dir bit(1), 

2 bit_count | fixed bin(24)) unaligned; 
where: 
Ls type specifies the storage system type of entry: 


0 ("00"b) link 
1 ("O1"b) segment 
2 ("10"p) directory _ 


ae nnames specifies the number \ of names for this entry that match 
star_name. 
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Bs nindex | Specifies the offset in the array of names (pointed to by 
n_ptr) for the first name returned for this entry. 

4, dtem is the date and time the directory entry for the segment or 
directory was last modified. 

ae padi is unused space in this structure. 

6. mode is the current user's access mode to the segment or directory. 
See "Access Modes" below. 

ie raw_mode is the current user's access mode before ring brackets. and 


access isolation are considered. 


8. master_dir specifies whether entry is a master directory: 
"1"b yes ; 
"O"b no 


9. bit_count is the bit count of the segment or directory. 


The structure used if the entry is a link is identical to the one used by 
hes_$star_list_ and identical information is returned by both entries for links. 


Entry: hes_$star_list_ 


This entry point returns more information about the selected entries, such 
as the mode and records used for Segments and directories and link pathnames for 
links. This entry point obtains the records used and the date of last 
modification and last use from the VTOC, and is, therefore, more expensive’ to 
use than the hes_$star_list_ entry point. 


Usage 
declare hes_$star_list_ entry (char(*), char(*), fixed bin(3), ptr, 
fixed bin, fixed bin, ptr, ptr, fixed bin(35)); 


call hes_$star_list_ (dir_name, star_name, select_sw, area_ptr, 
branch_count, link_count, entry_ptr, n_ptr, code); 


where; 
Ae dir_name is the pathname of the containing directory. (Input) 


2 star_name is the entryname that can contain asterisks or question 
marks. (Input) 


7/76 7-90 AK92A 


ww 


hes_$star_ hes_$star_ 


33 select_sw indicates what information is to be returned. (Input) It 

can be: 

1 information is returned about link entries only 

2 information is returned about segment and directory 
entries only 

3 information is returned about segment, directory, and 
link entries 

5 information is returned about link entries only, 
including the pathname associated with each link entry 

T information is returned about segment, directory, and 


link entries, including the pathname associated with 
each link entry 


4, area_ptr is a pointer to the area in which information is to be 
returned. If the pointer is null, branch count and 
link_count are set to the total number of selected 
entries. See "Notes" below. (Input) 


oe branch_count is a count of the number of segments and directories that 
match the entryname. (Output) 


6. link_count is a count of the number of links that match the 
entrynam2. (Output) 


LS entry_ptr is a pointer to the . allocated structure in which 
information on each entry is returned. (Output) 


8. n_ptr is a pointer to the allocated array in which selected 
entrynames and pathnames associated with link entries are 
stored. (Output) 


9. code is a storage system status code. See "Status Codes" 
below. (Output) 


Notes 


Even if area_ptr is null, branch count’ and link_count may be set. If 
information on segments and directories is requested, branch_count is set to the 
total number of segments and directories that match star_name. If information 
on links is requested, link_count is the total number of links that match 
star_name. : 


If area_ptr is not null, an array of entry information structures and _ the 
names array, as described in the hes_$star_ entry point above, are allocated in 
the user-supplied area. The number of structures allocated is count, which is 
equal to branch_count plus link_count. Each element in the structure array may 
be either of the structures described below (the links structure for links or 
the branches structure for segments and directories). The correct structure is 
indicated by the type item, the first item in both structures. | 


If the system is unable to access the VTOC entry for a branch, values of 
zero are returned for records used, date_time_contents_modified, and 
date_time_used, and no error code is returned. Callers of this entry point 
should interpret zeros for all three of these values as .an error indication, 
rather than as valid data. : : 
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The first three items in each Structure are identical to the ones in the 
structure returned by the hes_$star_ entry point. 


The following structure is used if the entry is a segment or a directory: 


del 1 branches (count) _ aligned based (entry_ptr), 

(2 type bit(2), 

2 nnames fixed bin(15), 

2 nindex fixed bin(17), 

2 dtem bit(36), 

2 dtu bit(36), 

2 mode bit(5), 

2 raw_mode bit(5), 

2 master_dir bit(1), 

2 records fixed bin(24)) unaligned; 
where: 
Ts type Specifies the storage system type of entry: 


0 ("00"b) link 
1 ("01"b) segment 
2 ("10"b) directory 


2. nnames Specifies the number of names for this entry that match 
Sstar_name. 

3 nindex specifies the offset in the array of names (pointed to by 
n_ptr) for the first name returned for this entry. 

eg dtcm is the date and time the contents of the segment or directory 
were last modified. ? 

on dtu is the date and time the segment or directory was last used. 

6. mode is the current user's access mode to the segment or directory. 

7. Yraw_mode is the current user's access mode before ring brackets” and 


access isolation are considered. 


8. master_dir specifies whether entry is a master directory: 


"I"b yes 
"ONMbh no 
9. records is the number of 1024-word records of secondary storage that 


have been assigned to the segment or directory. 


The following structure is used if the entry is a link: 


del 1 links (count) aligned based (entry_ptr), 

(2 type bit(2), 

2 nnames fixed bin(15), 

2 nindex fixed bin(17), 

2 dtem bit(36), 

2 dtd bit(36), 

2 pathname_len fixed bin(17), 

2 pathname_index fixed bin(17)) unaligned; 


7/76 ‘ 7-92 Oe AK92A 


C ; 


hes_$ 


star_ 


where: 

ks type 

age nnames 
nindex 

4, dtem 

oe dtd 

6. pathname_len 


is 
is 
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as above. 
as above. 
as above. 
and time the link was last modified. 


and time the link was last dumped. 


number of significant characters in the pathname 
associated with the link. 


ie pathname_index is the index in the array of names for the link pathname. 
If the pathname associated with each link was requested, the pathname is 
placed in the names array and occupies six units of this array. The index of 


the first unit is specified by pathname_index in the links array. The length of 
the pathname is given by pathname_len in the links array. 
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Name: hes_$wakeup 


The hes_$wakeup entry point sends an interprocess communication wakeup 
Signal to a specified process over a specified event channel. If that process 
had previously called the ipe_$block entry point, it would be awakened. See the 
ipec_ subroutine description in this document. 


sage 


declare aan entry (bit(36), fixed bin(71), fixed bin(71), fixed 
bin(35 


call hes_$wakeup (process_id, channel_id, message, code); 


where: 


ie process_id is the process identifier of the target process. (Input) 


2x channel_id is the identifier of the event channel over which the wen Oue is 
to be sent. (Input) 
32 message is the event message to be interpreted by the target process. 
(Input) 
4, code is a system status code. (Output) It can be one of the 
following: 
0 no error 
1 | Signalling was correctly done, but the 


target process was in the stopped state 


2 an input argument was incorrect, so 
Signalling was aborted 


3 the target process was not found (e.g.,. 
process_id was incorrect or the target 
process had been destroyed), so signalling 
was aborted 


error_table_$invalid_channel the channel identifier was not valid 
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Name: iod_info_ 


The iod_info_ subroutine extracts information from the I/O daemon tables 
needed by those commands and subroutines that submit I/O daemon requests. 


Entry: iod_info_$generic_type 


This entry point returns the generic type of a specified request type as 
defined in the I/0 daemon tables. For example, the generic type for the 
"unlined" request type might be "printer". Refer to the print_request_types 
command in the MPM Commands for information on generic types available for 
specific request types. 


Usage 


declare iod_info_$generic_type entry (char(*#*), char(32), fixed bin(35)); 


call iod_info_$generic_type (request_type, generic_type, code); 


where: 


Vs request_type is the name of a request type defined in the I/0 daemon 
tables. (Input) 


2. generic_type is the name of the generic type of the above request’ type. 
(Output) 

23 code is a standard status code. If the specified request type is 

; not found, the code error_table_$id_not_found is returned. 
(Output) 


Entry: iod_info_$driver_access_name 


This entry point returns the driver access name for a_ specified request 
type as defined in the I/O daemon tables. For example, the driver access name 
for the "printer" request type might be "TO.SysDaemon.*", 
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Usage 


declare iod_info_$driver_access_name entry (char(*), char(32), fixed 
bin(35)); 


call iod_info_$driver_access_name (request_type, access_name, code); 


where: 

Va request_type is the name of a request type defined in the I/O daemon 
tables. (Input) 

2% access_name is the driver access name for the above request type. 
(Output) 

3. code is a standard status code. If the specified request type is 
not found, the code error_table_$id_not_found is returned. 
(Output) 
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This subroutine performs I/O operations and some related functions. Most 
of the iox_ subroutine entry points are described in the MPM Subroutines. 


The following entry points are probably not of interest to every user. 
However, they are needed by any user who is writing his own I/0 module. For 
information on I/O module construction and the use of certain iox_ entry points, 
see "Writing an I/O Module" in Section IV. 


Entry: iox_$destroy_iocb 


This entry point frees the storage used by the control block for an I/0 
Switch. The switch must be in the detached state. Any existing pointers to the 
control block become invalid. 


Usage 


declare iox_$destroy_iocb entry (ptr, fixed bin(35)); 


call iox_$destroy_ioecb (iocb_ptr, code); 


where: 
ie iocb_ptr points to the I/O control block to be freed. (Input) 


2x code is an I/O system status code. (Output) 


Entries: forbear tines Tet acnea’ iox_$err_not_open, iox_$err_not_closed, 
iox_$err_not_attached 


These entry points accept any number of arguments, the last of which is 
fixed bin(35). Each entry point sets the last argument to the respective code: 
error_table_$no_operation, error_table_$not_open, error_table_$not_closed, or 
error_table_$not_attached. These entry points are assigned to entry variables 
in the I/O control block in order to return an error code when that entry 
variable is called. See "Writing an I/O Module" in Section IV for instructions 
on when to assign this entry point to such an entry variable. 


Usage 


declare iox_$err_no_operation entry options (variable) ; 
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Entry: iox_$find_iocb_n 


This entry point may be used to find all existing I/0 control blocks, 
whether attached or detached. It returns a pointer to the nth control block in 
the calling ring, the numbering being arbitrary. If there are fewer than n 
control blocks, a null pointer and the code error_table_$no_iocb are returned. 
Creating or destroying control blocks during a sequence of calls to this entry 
point should be avoided, as it causes unpredictable changes to the numbering. 


Usage 


declare iox_$find_iocb_n entry (fixed bin, ptr, fixed bin(35)); 
call iox_$find_iocb_n (n, iocb_ptr, code); _ 


where: 
1. on is the number of the I/O control block. (Input) 
2. iocb_ptr is a pointer to the control block. (Output) 


3. code is an I/O system status code. (Output) 


Entry: iox_$look_iocb 


This entry point returns a pointer to the control block for a specified I/0 
Switch. If the control block does not exist, it is not created, and a null 
pointer and the code error_table_$no_iocb are returned. 


Usage 


declare iox_$look_iocb entry (char(*), ptr, fixed bin(35)); 


call tox_$look_iocb (switchname, iocb_ptr, code); 


where: 
es switchname is the name of the I/O switch. (Input) 
2. iocb_ptr is a pointer to the control block. (Output) 


3. code is an I/O system status code. (Output) 
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ntry: iox_$propagate 
was! 
This entry point adjusts certain pointers and entry variables in an [1/0 
control block as required when changing between the states detached, 
attached-closed, and attached-open. It also reflects modifications to a control 
block to other control blocks that are synonyms (immediate or chained) for it. 
This entry point must be called at certain points in the code of an I/O module, 
and it must not be called in any other circumstances. See "Writing an I/0 
Module" in Section IV for instructions on when to call iox_$propagate. 
Usage 
declare iox_$propagate entry (ptr); 
call iox_$propagate (iocb_ptr); 
where iocb_ptr is a pointer to the control block. (Input) 
er 
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Name: ipe 


The Multics System supports an interprocess communication facility. The 
basic purpose of the facility is to provide control communication (by means of 
stop and go signals) between processes. 


The ipec_ subroutine is the user's interface to the Multics interprocess 
communication facility. Briefly, that facility works as follows: a process 
establishes event channels in the current protection ring and waits for an event 
on one or more channels. 


Event channels can be thought of as numbered slots in the interprocess 
communication facility tables. Each channel is either an event-wait or 
event-call channel. An event-wait channel receives events that are merely 
marked as having occurred and awakens the process if it is blocked waiting for 
an event on that channel. On an event-call channel, the occurrence of an _ event 
causes a specified procedure to be called if (or when) the process is blocked 
waiting for an event on that channel. Naturally, the specific event channel 
must be made known to the process that expected to notice the event. For an 
event to be noticed by an explicitly cooperating process, the event channel 
identifier value is typically placed in a known location of a shared segment. 
For an event to be noticed by a system module, a subroutine call is typically 
made to the appropriate system module. A process can go blocked waiting for an 
event to occur or can explicitly check to see if it has occurred. If an event 
occurs before the target process goes blocked, then it is immediately awakened 
when it does go blocked. 


The user can operate on an event channel only if his ring of execution is 
the same as his ring when the event channel was created (for a discussion of 
rings see "Intraprocess Access Control" in Section VI of the MPM Reference 
Guide). 


The hes_$wakeup entry point (described in this document) is used to wake up 
a blocked process for a specified event. 


Entry: ipe_$create_ev_chn 


This entry point creates an event-wait channel in the current ring. 


Usage 


declare ipc_$create_ev_chn entry (fixed bin(71), fixed bin(35)); 


-eall ipe_$create_ev_chn (channel_id, code); 


where: 
V4 channel_id is the identifier of the event channel..’« (Output) 
oO. code | is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 
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Entry: ipce_$delete_ev_chn 


This entry point destroys an event channel previously created by the 
process. 


Usage 


declare ipe_$delete_ev_chn entry (fixed bin(71), fixed bin(35)); 


call ipce_$delete_ev_chn (channel_id, code); 


where: 
Ves channel_id - is the identifier of the event channel. (Input) 
age code is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 


Entry: ipe_$dcel_ev_call_chn 


This entry point changes an event-wait channel into an event-call channel. 


- Usage 


declare ipce_$dcel_ev_call_chn entry (fixed bin(71), entry, ptr, fixed bin, 
fixed bin(35)); 


call ipe_$del_ev_call_echn (channel_id, procedure, data_ptr, priority, 


code); 

where: 

1. channel_id is the identifier of the event channel. (Input) 

2% procedure is the procedure entry point invoked when an event occurs 
on the specified channel. The procedure entry point 
should not be an internal procedure. (Input) 

3. data_ptr is a pointer to a region where data to be passed to. and 
interpreted by that procedure entry point is placed. 
(Input) 

4, priority se 2 is a number indicating the priority of this event-call 

a | , Channel as compared to other event-call channels declared 
by this process for this ring. If, upon interrogating all 
the appropriate event-call channels, more than one is 
found to have .received an event, the lowest-numbered 
priority is honored first, and so on. (Input) 

om code is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 


ipc_ ipe_ 


4, priority is a number indicating the priority of this event-call 
channel as compared to other event-call channels declared 
by this process for this ring. If, upon interrogating all 
the appropriate event-call channels, more than one is 
found to have received an event, the lowest-numbered 
priority is honored first, and so on. (Input) 


oe code is a nonstandard status code; see "Status Code Values" 
later in this description. (Output) 


Entry: ipc_$decl_ev_wait_chn 


This entry point changes an event-call channel into an event-wait channel. 


Usage 


declare ipc_$decl_ev_wait_chn entry (fixed ‘bin(71), fixed bin(35))3; 


call ipe_$decl_ev_wait_chn (channel_id, code); 


where: 
Ts channel_id is the identifier of the event channel. (Input) 
2. code is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 


Entry: ipe_$drain_chn 


This entry point resets an event channel so that any pending events (i.e., 
events that have been received but not processed for that channel) are removed. 


Usage 


declare ipc_$drain_chn entry (fixed bin(71), fixed bin(35)); 


call ipe_$drain_chn (channel_id, code); 


where: 
1. channel_id is the identifier of the event channel. (Input) 
2. code is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 
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ntry: ipe_$cutoff 


This entry point inhibits the reading of events ona specified event 
channel. Any pending events are not affected. More can be received, but do 
not cause the process to wake up. 


Usage 


declare ipe_$cutoff entry (fixed bin(71), fixed bin(35)); 


call ipe_$cutoff (channel_id, code); 


where: 
ls channel_id is the identifier of the event channel. (Input) 
2s code is a nonstandard status code; see "Status Code Values" 


later in this description. (Output) 


Entry: ipce_$reconnect 


This entry point enables the reading of events on a specified event channel 
for which reading had previously been inhibited (using the ipc_$cutoff entry 
point). All pending signals, whether received before or during the time reading 
was inhibited, are henceforth available for reading. 


Usage © 


declare ipce_$reconnect entry (fixed bin(71), fixed bin(35)); 


call ipce_$reconnect (channel_id, code); 


where: 

ns channel_id is the identifier of the event channel. (Input) 

24 code is a nonstandard status code; see "Status Code Values" 
a later in this description. (Output) 

ntry: ipe_$set_wait_prior 


This entry point causes event-wait channels to be given priority over 
event-call channels when several. channels are being interrogated; e.g., when a 
process returns from being blocked and is waiting on any of a list of channels. 
Only event channels in the current ring are affected. 
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Usage 


declare ipce_$set_wait_prior entry (fixed bin(35)); 


call ipe_$set_wait_prior (code); 


where code is a nonstandard status code; see "Status Code Values" later in this 
description. 


Entry: ipce_$set_call_prior 


This entry point causes event-call channels’ to be given priority over 
event-wait channels when several channels are being interrogated; e.g., upon 
return from being blocked waiting oon any of a list of channels. Only event 
channels in the current ring are affected. By default, event-call channels have 
priority. 


Usage 


declare ipc_$set_call_prior entry (fixed bin(35)); 


call ipe_$set_call_prior (code); 


where code is a nonstandard status code; see "Status Code Values" later in this 
description. 


Entry: ipc_$mask_ev_calls 


This entry point causes the ipe_$block entry point (see below) to 
completely ignore event-call channels occurring in the user's ring at the time 
of this call. 


Usage 


declare ipc_$mask_ev_calls entry (fixed bin(35)); 


call ipe_$mask_ev_calls (code); 


where code is a nonstandard status code; see "Status Code Values" later in this 
description. | 
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ntry: ipc_$unmask_ev_calls 


This entry point reverses the effect of the ipe_$mask_ev_calls entry point. 


Usage 


declare ipe_$unmask_ev_calls entry (fixed bin(35)); 


call ipe_$unmask_ev_calls (code); 


where code is a nonstandard status code; see "Status Code Values" later in this 
description. 


Entry: ipe_$block 


This entry point blocks the user's process until one or more of a specified 
list of events has occurred. 


Usage 


declare ipe_$block entry (ptr, ptr, fixed bin(35)); 
call ipe_$block (wait_list_ptr, info_ptr, code); 


where: 
Ts wait_list_ptr is a pointer to the base of a structure that specifies the 
channels on which events are being awaited. (Input) 
del 1 wait_list based, 
2 nchan fixed bin, 
2 channel_id (nchan) fixed bin(71); 
where: 
nechan is the number of channels. 
channel_id is an array of channel identifiers selecting 
the channels to wait on. 
ae info_ptr is a pointer to the base of a structure into which the 


ipe_$block entry point can put information about the event 
that caused it to return (i.e., that awakened the 
process). (Input) 


del 1 event_info, 
2 channel_id fixed bin(71), 
2 message fixed bin(71), 
2 sender bit(36), 
2 origin, 
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3 dev_signal bit(18) unaligned, 
3 ring bit(18) unaligned, 
2 channel_index fixed bin; 
where: 
channel_id is the identification of the event 
channel. | 
message is an event message as specified to the 
hes_$wakeup entry point. 
sender is the process identifier of the sending 
process. 
dev_signal indicates whether this event occurred as 
the result of an I/O interrupt. 
71d yes 
"ONb no 
ring is the sender's validation level. 


channel_index is the’ index of channel_id in the 
wait_list structure above. | 


35 code is a nonstandard status code; see "Status Code Values" 
later in this description. (Output) 


Entry: ipe_$read_ev_chn 


This .entry point: reads the information about an event on a specified 
channel if the event has occurred. 


Usage 


declare ipe_$read_ev_chn entry (fixed bin(71), fixed bin, ptr, fixed 
bin(35));. 


call ipce_$read_ev_chn (channel_id, ev_occurred, info_ptr, code); 


where: 
1. channel_id is the identifier of the event channel. (Input) 
2. ev_occurred indicates whether an event occurred on the specified 
| channel. * (Qutput) 
0) no event occurred | 
1 an event occurred 
ca info_ptr 3 is as above. (Input) 7 4 
4, code is a nonstandard status code; see "Status Code Values" 


below. (Output) 
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All of the entry points described above return a value from 0 to 5 for the 
code argument. The values mean the following: 


0 no error. 

1 ring violation; e.g., the event channel resides in a ring that 
is not accessible from the caller's ring. . 

2 the table that contains the event channels for a given ring was 
not found. | 

3 the specified event channel was not found. 

4 a logical error in uSing the ipc_ subroutine was encountered; 


e€.g., waiting on an event-call channel. 


5 a bad argument was passed to the ipe_ subroutine; e.g., a 
zero-value event channel identifier. 


nvokin n Event-Call Procedur 


When a process is awakened on an event-call channel, control is immediately 
passed to the procedure’ specified by the ipce_$dcel_event_call_channel entry 
point. The procedure is called with one argument, a pointer to the following 
structure: 


dcl 1 event_info based, 
2 channel_id fixed bin(71), 
2 message fixed bin(71), 
2 sender bit(36), 
2 origin, 
3 dev_signal bit(18) unaligned, 
3 ring bit(18) unaligned, 
2 data_ptr ptr; 
where: 
1% channel_id is the identifier of the event channel. 
2. message is an event message as specified to the hes_$wakeup entry 
point. 
Se sender | is the process identifier of the sending process. 

_&, dev_signal indicates whether the event occurred as the result of an I/0 
interrupt. ) 
wq7tbh : yes 
a OL 0) no 

D6 ring is the sender's validation level. 
6: data_ptr points to further data to be used by the called procedure. 
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Name: match_star_name_ 


The match _star_name_ subroutine implements the Multics storage system star 
convention by comparing an entryname with a name containing stars or question 
marks (called a star name). Refer to "Constructing and Interpreting Names" in 
Section I of the MPM Commands for a description of the star convention and a 
definition of acceptable star name formats. 


Usage 


declare match _star_name_ entry (char(*), char(*), fixed bin(35)); 


call match_star_name_ (entryname, star_name, code); 


where: 

Te entryname is the entryname to be compared with the star name. 
Trailing spaces in the entryname are _ignored. 
(Input) 7 

2% star_name is the star name with which entryname is compared. 
Trailing spaces in the star name are ignored. 
(Input) 

3. code is a standard status code. (Output) It can be: 

0 | the entryname matches the star name 


error_table_$nomatch the entryname does not match the star name 


error_table_$badstar the star name does not have an acceptable format 


Notes 


Refer to the description of the hes_$star_ entry point in this document to 
see how to list the directory entries that match a given star name. 


Refer to the description of the check_star_name_ subroutine in this 
document to see how to validate a star name. 
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Name: msf_manager_ 


The msf_manager_ subroutine is designed to provide a centralized and 
consistent facility for handling multisegment files. Multisegment files are 
files that can require more than one segment for’ storage. Examples of 
multisegment files are listings, data used through I/0 Switches, and APL 
workspaces. The msf_manager_ subroutine makes multisegment files almost as easy 
to use as single segment files in many applications. 


A multisegment file is composed of one or more components, each the size 
of a segment, identified by consecutive unsigned integers. Any word in a single 
Segment file can be specified by a pathname and a word offset. Any word ina 
multisegment file can be specified by a pathname, component number, and _ word 
offset within the component. The msf_manager_ subroutine provides the means for 
creating, accessing, and deleting components, truncating the multisegment file, 
and controlling access. | 


| In this implementation, a multisegment file with only component 0 is stored 
as a single segment file. If components other than 0 are present, they are 
stored as segments with names corresponding to the ASCII representation of their 
component numbers in a directory with the pathname of the multisegment file. 


To keep information between calls, the msf_manager_ subroutine stores 
information about files in per-process data structures called file control 
blocks. The user is returned a pointer to a file control block by the entry 
point msf_manager_$open, this pointer, fcb_ptr, is the caller's meéans of 
identifying the multisegment file to the other msf_manager_ entry points. The 
file control block is freed by the msf_manager_$close entry point. 


Entry: msf_manager_$open 


The msf_manager_$open entry point creates a file control block and returns 
a pointer to it. The file need not exist for a file control block to be created 
for it. 


Usage 


declare msf_manager_$open entry (char(*), char(*), ptr, fixed bin(35)); 


call msf_manager_$open (dir_name, entryname, fcb_ptr, code); 


where: 
1. dir_name is the pathname of the containing directory. (Input) 


2% entryname is the entryname of the multisegment file. (Input) 
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3. feb_ptr is a pointer to the file control block. (Output) 

4, code is a storage system status code. The code error_table_$dirseg 
is returned when an attempt is made to open a directory. 
(Output) | | 


Entry: msf_manager_$get_ptr 


The msf_manager_$get_ptr entry point returns a pointer to a_ specified 
component in the multisegment file. The component can be created if it does not 
exist. If the file is a single segment file, and a component greater than 0 is 
requested, the single segment is converted to a multisegment file. This change 
does not affect a previously returned pointer to component 0. 


Usage 
declare msf_manager_$get_ptr entry (ptr, fixed bin, bit(1), ptr, fixed 


bin(24), fixed bin(35)); 


call a ee (feb_ptr, component, create_sw, seg_ptr, bce, 
code); 


where: 


Tse feb_ptr is a pointer to the file control block. (Input) 
2. component is the number of the component desired. (Input) 
3. create_sw is the create switch. (Input) 


wa" b create the component if it does not exist 
"O"b do not create the component if it does not exist 


y, seg ptr is a pointer to the specified component in the file, or null 
(if there is an error). (Output) 

on be | is the bit count of the component. (Output) 

6. code is a storage system status code. (Output) It may be one of 


the following: 
error_table_$namedup if the specified segment already exists or the 
specified reference name has already been 
initiated 


error_table_$segknown if the specified segment is already known 
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Entry: msf_manager_$adjust 


The msf_manager_$adjust entry point optionally sets the bit count, 
truncates, and terminates the components of a multisegment file. It must be 
told the number of the last component and its bit count. The bit counts of all 
components with numbers less than the given component are set to 
sys_info$max_seg_size*36. All components with numbers greater than the given 
component are deleted. All components that have been initiated are terminated. 
A 3-bit switch is used to control these actions. 


Usage 


declare msf_manager_$adjust entry (ptr, fixed bin, fixed bin(24), bit(3), 
fixed bin(35)); 


call msf_manager_$adjust (feb_ptr, component, bc, switch, code); 


where: 
1. feb_ptr is a pointer to the file control block. (Input) 
2 component is the number of the intended last component. (Input) 
3. be is the bit count to be placed on the last component. (Input) 
mT switch is a 3-bit count/truncate/terminate switch. (Input) 
bit count 


"O"b do not set the bit count 
"1I"b set the bit count 


truncate 
"O"b do not truncate the given component 
"1"b truncate the given component to the length specified 
in the be argument 
terminate : | 
"O"b do not terminate the component 
"1"b terminate the component 


5% code is a storage system status code. (Output) 
ntry: msf_manager_$close 


This entry point terminates all components that the file control block 
indicates are initiated and frees the file control block. 
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Usage 


declare msf_manager_$close entry (ptr); 


call msf_manager_$close (feb_ptr); 


where feb_ptr is the pointer to the file control block. (Input) 


Entry: msf_manager_$acl_list 


7 This entry point returns the access control list (ACL) of a multisegment 
file. 


Usage 
declare msf_manager_$acl_list entry (ptr, ptr, ptr, fixed bin, ptr, fixed 
bin(35)); 
call msf_manager_$acl_list (fcb_ptr, area_ptr, area_ret_ptr, acl_ptr, — 


acl_count, code); 


where; 
Ts feb_ptr is a pointer to the file control block. (Input) 
2. area_ptr points to an area in which the list of ACL entries, which 


make up the entire ACL of the multisegment file, is 
allocated. If area_ptr is null, then the user wants access 
modes for certain ACL entries; these will be specified by 
the structure pointed to by acl_ptr (see below). (Input) 


3% area_ret_ptr points to the start of the allocated list of ACL entries. 


(Output) 
4, acl_ptr if area_ptr is null, then acl_ptr points to an ACL 
structure, segment_acl, (described in "Notes" below) into 


which mode information is placed for the access’ names 
specified in that same structure. (Input) 


on acl_count is the number of entries in the segment_acl structure. 
(Input or Output) 
Input is the number of entries in the ACL structure 


ey . identified by acl_ptr 
Output is the number of entries in the  segment_acl 
structure allocated in the area pointed to by 
area_ptr, if area_ptr is not null 


6. code 24 ‘18 a storage system status code. (Output) 
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The following is the segment_acl structure: 


del 1 segment_acl (acl_count) aligned based (acl_ptr), 
2 access_name echar(32), 
2 modes bit(36), 
2 zero_pad bit(36), 
2 status_code fixed bin(35); 
where: 


ae access_name is the access name (in the form Person_id.Project_id.tag) 
' that identifies the process to which this ACL entry applies. 


25 modes contains the modes for this access name. The first three 
bits correspond to the modes read, execute, and write. The 
remaining bits must be O's. For example, rw access is 
expressed as "101"b. 

3. zero_pad must contain the value zero. (This field is for use with 
extended access and may only be used by the systen.) 


4, status_code is a storage system status code for this ACL entry only. 


If acl_ptr is used to obtain modes for specified access names (rather than 
obtaining modes for all access names in area_ret_ptr), then each ACL entry in 
the segment_acl structure either has status_code set to 0 and contains the 
multisegment file's mode or has status_code set to error_table_$user_not_found 
and contains a mode of 0. 


Entry: msf_manager_$acl_replace 


This entry point replaces the ACL of a multisegment file. 


Usage 


declare msf_manager_$acl_replace entry (ptr, ptr, fixed bin, bit(1), fixed 
bin(35)); 


call msf_manager_$acl_replace (feb_ptr, acl_ptr, acl_count, no_sysdaemon_sw 


code); 
where: 
Ts feb_ptr is a pointer to the file control block. (Input) 
2. acl_ptr | points’ to the user-Supplied segment_acl structure 


(described in the msf_manager_$acl_list entry point above) 
that is to replace the current ACL. (Input) 
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3. acl_count is the number of entries in the segment_acl structure. 
(Input) | 


4, no _sysdaemon_sw is a switch that indicates whether an rw *.SysDaemon.* 
entry is ta be put on the ACL of the multisegment file 
after the existing ACL has been deleted and before _ the 
user-supplied segment_acl entries are added. (Input) 

"Ob adds rw *.SysDaemon.* entry 
"1"b replaces the existing ACL with only the 
user-supplied segment_acl 


5. code is a storage system status code. (Output) 


Notes 


If acl_count is zero, the existing ACL is deleted and only the action 
indicated (if any) by the no —Ssysdaemon_ sw switch is performed. If acl_count is © 
greater than zero, processing of the segment_acl entries is performed top to 
bottom, allowing a later entry to overwrite a previous one if the access_name in 
the segment_acl structure is identical. © 


Entry: msf_manager_$acl_add 


This entry point adds the specified access modes to the ACL of the 
multisegment file. 


Usage - 


declare msf_manager_$acl_add entry (ptr, ptr, fixed bin, fixed bin(35)); 


call msf_manager_$acl_add (fcb_ptr, acl_ptr, acl_count, code); 


where: 
ie feb_ptr is a pointer to the file control block. (Input) 
2s acl_ptr points to the user-supplied segment_acl structure (described in 
the msf_manager_$acl_list entry point above). (Input) 
353 acl_count is the number of ACL entries in the segment_acl structure. 
, (Input) 
4. eode is a storage system status code. (Output) 
ote 


If code is returned as error_table_$argerr, then the erroneous ACL entries 
in the segment_acl structure have status_code set to an appropriate error code. 
No processing is performed. 
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ntry: msf_manager_$acl_delete 


This entry point deletes ACL entries from the ACL of a multisegment file. 


Usage 


declare msf_manager_$acl_delete entry (ptr, ptr, fixed bin, fixed bin(35)); 


call msf_manager_$acl_delete (fceb_ptr, acl_ptr, acl_count, code); 


where: 
is feb_ptr is a pointer to the file control block. (Input) 
2s acl_ptr points to a user-supplied delete_acl structure. see "Notes" 


below. (Input) 


3. acl_count is the number of ACL entries' in the delete_acl_ structure. 
(Input) | 


4, code is a storage system status code. (Output) 


Notes 


The delete_acl structure is as follows: 


del 1 delete_acl (acl_ count) aligned based (acl_ptr), 
2 access_name ehar(32), 
2 status_code fixed bin(35); 
where: 


TV access_name is the access name (in the form Person_id.Project_id.tag) of 
an ACL entry to be deleted. 


Ze status_code is a storage system status code for this ACL entry only. 


If code is error_table_$argerr, no processing is performed and status_code 
in each erroneous ACL entry is set to an appropriate error code. 


If ‘an access name matches no name already on the ACL, then the status_code 
for that delete_acl entry is set to error_table_$user_not_found. Processing 
continues to the end of the delete_acl structure and code is returned as 0. 
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Name: object_info_ 


The object_info_ subroutine returns structural and identifying information 
extracted from an object segment. It has three entry points returning 
progressively larger amounts of information. All three entry points have 
identical calling sequences, the only distinction being the amount of 
information returned in the information structure described below. This 
Structure can be found in the object_info.inel.pl1 include file. 


Entry: object_info_$brief 


This entry point returns. only the structural information necessary to 
locate the object's major sections. 


Usage 


~ 


s 
! 


declare object_info_$brief entry (ptr, fixed bin(24), ptr, fixed bin(35)); 


call object_info_$brief (seg_ptr, be, info_ptr, code); 


where: 

1. seg_ptr is a pointer to the base of the object segment. (Input) 

2. be is the bit count of the object segment. (Input) 

Ss info_ptr is a pointer to the info structure in which the object 
information is returned. See "Information Structure" later in 


this description. (Input) 


4, code is a standard status code. (Output) 


ntry: object_info_$display 


This entry point returns, in addition to the information returned in the 
object_info_$brief entry point, all the identifying data required by certain 
object display commands, such as the print_link_info command (described in this 
document). 


er eee ee ft Ree | 
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declare object_info_$display entry (ptr, fixed bin(24), ptr, fixed 
bin(35)); | 
call object_info_$display (seg_ptr, be, info_ptr, code); 
where seg_ptr, be, info_ptr, and code are as above. 
Entry: object_info_$long 
This entry ‘point returns, in addition to the information supplied by the 
object_info$display entry point, the data required by the Multics binder. 
Usage | . 
declare object_info $long entry (ptr, fixed bin(24), ptr, fixed bin(35)); 
call object_info_$long (seg_ptr, bce, info_ptr, code); 
where seg ptr, bc, info_ptr, and code are the same as in the object_info_$brief 
entry point above. wes 
information Structure 
The information structure is as follows: 
del 1 object_info aligned, 
2 version_number fixed bin, 
2. text_ptr ptr, 
2 def_ptr ptr, 
2 link_ptr ptr, 
2 stat_ptr ptr, 
2 symb_ptr ptr, 
2 bmap_ptr ptr, 
2 ting fixed bin(18), 
2 ding a fixed bin(18), 
2 ling fixed bin(18), 
2 ilng fixed bin(18), 
' 2 slng . fixed bin(18), 
2 blng  .fixed bin(18), 
2 format, me 
3 old_format bit(1) unaligned, 
3 bound bit(1) unaligned, 
3 relocatable -bit(1) unaligned, 
3 procedure 7 bit(1) unaligned, 
3 standard bit(1) unaligned, wat! 
3 gate bit(1) unaligned, 
3 separate_static bit(1) 


unaligned, 
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3 links_in_ text 


3 pad 
2 entry_bound 
2 textlink_ptr 


bit(1) unaligned, 
bit(28) unaligned, 
fixed bin, 

ptr, 


/*This is the limit of the $brief info structure.#/ 


compiler 
compile_time 
access _ name 
evers 
3 offset 
3 length 
2 comment, 

3 offset 

3 length 
2 source_map 


NO POD Po 


/*This is the limit of the $display 


rel_text 
rel_def 
rel_link 
rel_static 
rel_symbol 
text_boundary 


POM PM PDP NP NO lO Po 


Static_boundary 
default_truncate 
optional_truncate 


char(8) aligned, 
fixed bin(71), 
char(32) aligned, 
aligned, 

bit(18) unaligned, 
bit(18) unaligned, 


bit(18) unaligned, 
bit(18) unaligned, 
fixed bin, | 


ptr, 
ptr, 
ptr, 
ptr, 
ptr, — 
fixed 
fixed 
fixed 
fixed 


bin, 
bin, 
bin, 
bin; 


/*This is the limit of the $long info structure. *#/ 


where: 


— 


1. 


oO Oo foe NN WDB YO FSF WY Pp 


version_number 


text_ptr 
def_ptr 
link_ptr 
stat_ptr 
Symb_ptr 
bmap_ptr 
tiling 
ding 
ling 


number is 2). 


is a pointer to the base 


info structure. */ 


a 


object_info_ 


TRE TE EG SEES, 


is the version number of the structure (currently this 


of the 


is a pointer to the base of the 


is a pointer to the base of the 


is a pointer to the base of the 


is a pointer to the base of the 


is a pointer to the break map. 
is the length (in words) of the 
is the length (in words) of the 


is the length (in words) of the 
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This value is input. 


text section. 
definition section. 
linkage section. 
static section. 


symbol section. 


text section... 


definition section. 


linkage section. 


AK92 


11. 
12. 
13. 
14. 


15. 


16. 


eee 


18. 


19. 


20. 


21. 


22. 
23% 
24. 


This 
25: 


26. 
27. 


object_info_ 


ilng 

sing 

bing 
old_format 
bound 
relocatable 


procedure 


standard 


gate 


separate_static 


links_in_text 


pad 
entry_bound 


textlink_ptr 


is the limit of the 


compiler 


compile time 


access_name 


MOD the 


ebject_info_ 


A A 


is the length (in words) of the static section. 
is the length (in words) of the symbol section. 
is the length (in words) of the break map. 


indicates the format of the segment. 
"1"> old format 
"O"b new format 


indicates whether the object segment is bound. 
WA" D it is a bound object segment 
"O"b it is not a bound object segment 


indicates whether the object is relocatable. 
bi idl ©. the object is relocatable 
"O"b the object is not relocatable 


indicates whether the segment is a procedure. 
WL" it is a procedure 

"O"b it is nonexecutable data 
indicates whether the segment is a object 
segment. 

"1b it is a standard object segment 

"Ob. it is not a standard object segment 


standard 


indicates whether the procedure is generated in the 
gate format. 

le a @) it is in the gate format 

"O"b it is not in the gate format 

indicates whether the static section is separate from 
the linkage section. 


wT" b static section is separate from linkage section 

"O"b Static section is not separate from linkage 
section 

indicates whether the object segment contains 


text-embedded links. 
wT"b the object segment contains text-embedded links 
object segment does not contain 
text-embedded links | 


is currently unused. 
is the entry bound if this is a gate procedure. 
link if 


is a pointer to the first text-embedded 


links_in_text is equal to "1"b. 
info structure for the object_info_$brief entry point. 


is the name of the compiler that generated this object 
segment. 


is the date and time this object was generated. 
is the access identifier (in the form 


Person_id.Project_id.tag) of the user in whose behalf 
this object was generated. 
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28. cvers.offset 


29. cvers.length 


30. comment.offset 


31. comment.length 


32. source_map 

This is the limit of 
point. 

33. rel_text 

34. rel_def 

35. rel_link 

36. rel_static 


37. rel_symbol 


38. text_boundary 


39. static_boundary 


40. default_truncate 


41. optional_truncate 


object_info_ 


eee a 


is the offset (in words), relative to the base of the 
symbol section, of the aligned variable length 


oe String that describes the compiler version 
used. 


is the length (in characters) of the compiler version 
String. 


is the offset (in words), relative to the base of the 
Symbol section, of the aligned variable length 
character string containing some compiler-generated 
comment. 7 


is the length (in characters) of the comment string. 


is the offset (relative to the base of the symbol 
section) of the source map. 


the info structure for the object_info_$display entry 


is a pointer to the object's text section relocation 
information. 


is a pointer to the object's definition section 
relocation information. 


is a pointer to the object's linkage section 
relocation information. 


is a pointer to the object's static section relocation 
information. . 


is a pointer to the object's symbol section relocation 
information. 


partially defines the beginning address of the text 
section. The text must begin on an integral multiple 
of some number, e.g., O mod 2, O mod 64; this is that 
number. 


is analogous to text_boundary for internal static. 


is the offset (in words), relative to the base of the 
Symbol section, starting from which the symbol section 
can be truncated to remove nonessential information 
(e.g., relocation information). 


is the offset (in words), relative to the base of the 
Symbol section, starting from which the symbol section 
can be truncated to remove unwanted information (e.g., 
the compiler symbol tree). 


This is the limit of the info structure for the object_info_$long entry point. 
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Name: prepdre_mc_restart_ 


The prepare_mc_restart_ subroutine should be called by a condition handler, 
which was invoked as a result of a hardware-detected condition, if the handler 
wishes the process to: 


V4 retry the faulting instruction 


2. skip the faulting instruction and continue 
3% execute some other instruction instead of the faulting instruction and 
continue 


4, resume execution at some other location in the same program 


When a condition handler is invoked for a hardware-detected condition, it 
is passed a pointer to the machine-conditions data at the time of the fault. If 
the handler returns, the system attempts to restore these machine conditions and 
restart the process at the point of interruption encoded in the 
machine-conditions data. After certain conditions, however, the hardware is 
unable to restart the processor. In other cases, an attempt to restart always 
causes the same condition to occur again, because the system software has 
already exhausted all available recovery possibilities (e.g., disk read errors). 


The prepare_mc_restart_ subroutine is provided to check machine conditions 
for restartability, and to make modifications to the machine conditions (to 
accomplish user modifications to process execution) before a condition handler www! 
returns. 


ntry: prepare_mc_restart_$retry 


This entry point is called to prepare the machine conditions for retry at 
the point of the hardware-detected condition. For example, this operation is 
appropriate for a linkage error signal, resulting from the absence of a segment, 
that the condition handler has been able to locate. 


Usage 


declare prepare_mc_restart_$retry entry (ptr, fixed bin(35)); 


call prepare_mc_restart_$retry (mc_ptr, code); 


where: 

13 mec_ptr is a pointer to the machine conditions. (Input) 

ae code is a standard status code. If it is nonzero on return, the 
machine conditions cannot be restarted. see "Notes" below. 
(Output) wa! 
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Entry: prepare_mc_restart_$replace 


This entry point is called to modify machine-conditions data so that the 
process executes a specified machine instruction, instead of the faulting 
instruction, and then continues normally. 


Usage 


declare prepare_mc_restart_$replace entry (ptr, bit(36), fixed bin(35)); 


call prepare_mc_restart_$replace (mc_ptr, new_ins, code); 


where: 

ue mc_ptr is as aheue:: (Input) 

roa new_ins is the desired substitute machine instruction. (Input) 
3. code is as above. (Output) 


Entry: prepare_mc_restart_$tra 


This entry point is called to modify machine conditions data so that the 
procesS resumes execution, taking its next instruction from a_ specified 
location. The instruction transferred to must be in the same segment that 
caused the fault. 


Usage 


declare prepare_mc_restart_$tra entry (ptr, ptr, fixed bin(35)); 


call prepare_mc_restart_$tra (mc_ptr, newp, code); 


where; 

Vs mc_ptr is the same as in the prepare_mc_restart_$retry entry point 
above. (Input) 

2. newp is used in replacing the instruction counter in the machine 
conditions. (Input) : 

oe code is the same as in the prepare_mc_restart_$retry entry point 


above. (Output) 
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Notes 


For all entry points in the prepare_mc_restart_ subroutine, a pointer to 
the hardware machine conditions is required. The format of the machine 
conditions is described in "Multics Condition Mechanism" in Section VI of the 
MPM Reference Guide. 


For all entry points in the prepare_mc_restart_ subroutine, the following 
codes can be returned: 


error_table_$badarg an invalid mc_ptr was provided 
error_table_$no_restart the machine conditions cannot be restarted 
error_table_$bad_ptr the restart location is not accessible 


error_table_$useless_ restart the same error will occur again if restart 
is attempted : 
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Name: read_allowed_ 


The read_allowed_ subroutine determines whether a subject of specified 
authorization has access (with respect to the access isolation mechanism) to 
read an object of specified access class. 


Usage 
declare read_allowed_ entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); | 


returned_bit = read_allowed_ (authorization, access_class) ; 


where: 


age authorization is the authorization of the subject. (Input) 

2 access_class is the access class of the ‘object. (Input) 

Ss returned_bit indicates whether the subject is allowed to read the object. 
(Output) 


"7b read is allowed 
"QOMb read is not allowed 
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Name: read_write_allowed_ 


The read_write_allowed_ Subroutine determines whether a subject of 
Specified authorization has access (with respect to the access isolation 
mechanism) to read and write an object of specified access class. 


Usage 


declare read_write_allowed_ entry (bit(72) aligned, bit(72) aligned) 
returns (bit(1) aligned); 


returned_bit = read_write_allowed_ (authorization, access_class) ; 


where: 

Ve authorization is the authorization of the subject. (Input) 

23 access_class is the access class of the object. (Input) 

35 returned_bit indicates whether the subject is allowed to both read and 


write the object. (Output) 
"1"b read and write are allowed 
"O"b read and write are not allowed 
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Name: release_area_ 


The release_area_ subroutine is used to clean up an area after it is no 
longer needed. If the area is a segment acquired via the define_area_ 
subroutine, the segment is released to the free pool via the temporary segment 
manager. If the area was not acquired (only initialized) via the define _area_ 
subroutine then the area itself is reinitialized to the empty state. In any 
case, segments acquired to extend the area are released to the free pool of 
temporary segments. 


Usage 


declare release_area_ entry (ptr); 


call release_area_ (area_ptr); 


where area_ptr points to the area to be released. (Input) 
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The signal_ subroutine signals the occurrence of a given condition. A 
description of the condition mechanism and the way in which a handler 1s invoked 
by the signal_ subroutine is given in the "Multics Condition Mechanism" in 
Section VI of the MPM Reference Guide. 


Usage 


declare signal_ entry (char(*), ptr, ptr); 


call signal. (name, me_ptr, info_ptr); 


where: 
Ve name is the name of the condition to be signalled. (Input) 


2% mec_ptr points to the machine conditions at the time the condition was 
raised. This argument is used by system programs only in order 
to signal hardware faults. In user programs, this argument 
should be null if a third argument is supplied. This argument is 
optional. (Input) 


ce info_ptr points to information relating to the condition being raised. 
The structure of the information is dependent upon the condition 
being signalled; however, conditions raised with the same name 
should provide the information in the same structure. All 
structures must begin with a standard header. The format for the 
header as well as the structures provided with system conditions 
are described in "List of System Conditions and Default Handlers" 
in Section VI of the MPM Reference Guide. This argument is 
intended for use in signalling conditions other than hardware 
faults. This argument is also optional. (Input) 


Notes 


If the signal. subroutine returns to its caller, indicating that the 
handler has returned to it, the calling procedure should retry the operation 
that caused the condition to be signalled. 


The PL/I signal statement differs from the signal_ subroutine in that the 
above parameters cannot be provided in the signal statement. Also, for 
PL/I-defined conditions, a call to the signal_ subroutine is not equivalent to a 
PL/I signal statement since information about these conditions is kept 
internally. 
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Name: stu_ 


The stu_ (symbol table utility) subroutine provides a number of entry 
points for retrieving information from the runtime symbol table section of an 
object segment generated by the PL/I, FORTRAN, or COBOL compilers. (See the 
pli, fortran, and cobol commands in the MPM Commands.) A runtime Symbol table 
1S produced when a program is compiled with the -table control argument or when 
a runtime symbol table is required to support a feature of the language such as 
PL/I data-directed or FORTRAN NAMELIST input/output statements. A partial 
Symbol table, containing only a statement map, is produced when a program is 
compiled with the -brief_table control argument. 


Entry: stu_$find_header 


This entry point, given an ASCII name and/or a pointer to any location ina 
(possibly bound) object Segment, searches the given segment for the Symbol table 
header corresponding to the designated program. 


Usage 


declare stu_$find_header entry (ptr, char(32) aligned, fixed bin(24)) 
returns (ptr); 


header_ptr = stu_$find_header (seg_ptr, name, be); 


where; 

1. seg ptr points to any location in the object segment. (Input) 

2. name is the ASCII name of the program whose symbol header is to 
be found. If seg_ptr is null, name is treated as a 
reference name and the segment is determined according to 
the user's search rules. If the designated segment is 
bound, name specifies the component. (Input) 

3 be is the bit count of the object segment; if 0, the 
stu_$find_header entry point determines the bit count 
itself. (Input) 

4, header_ptr points to the Symbol table header if it is found or is null 
if the header is not found. (Output) 

Note 


Since determining the bit count of a segment is relatively expensive, the 
user should provide the bit count if he has it available (e.g., as a result of a 
call to hes_$initiate_count, described in the MPM Subroutines). 
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Entry: stu_$find_block 


This entry point, given a pointer to the symbol table header of an object 
segment, searches the runtime symbol table of the object segment for the 
runtime_block node that corresponds to a given procedure block in the object 
program. 


Usage 


declare stu_$find_block entry (ptr, char(*) aligned) returns (ptr); 


block_ptr = stu_$find_block (header_ptr, name); 


where: 

Ts header_ptr points to a symbol table header. (Input) 

2. name is the ASCxI name of the runtime_block node to be _ found. 
The name of a runtime_block node is the same as the first 
name written on the procedure statement that corresponds’ to 
the runtime_block node. (Input) © 

3% block_ptr is set to point to the runtime_block node if it is found or 


is null if the block is not found. (Output) 


Entry: stu_$get_runtime_block 


This entry point, given a pointer to an active stack frame and a location 
within the object segment that created the frame, returns pointers to the symbol 
table header of the object segment and the runtime_block node that corresponds 
to the procedure or begin block associated with the stack frame. Null pointers 
are returned if the stack frame does not belong to a PL/I, FORTRAN, or COBOL 
program or if the object segment does not have a runtime symbol table. 


Sage 


declare stu_$get_runtime_block entry (ptr, ptr, ptr, fixed bin(18)); 


call stu_$get_runtime_block (stack_ptr, header_ptr, block_ptr, loc); 


where: 

1% stack_ptr points to an active stack frame. (Input) 

2. header_ptr is set to point to the symbol table header or is null if the 
object segment does not have a runtime symbol table. 
(Output) 
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3 block_ptr is set to point to the runtime_block node that corresponds 
to the procedure or begin block associated with the stack 
frame or is null if the object segment does not have a 
runtime symbol table. (Output) 


y, loc is an address within the object segment (e.g., where 
execution was interrupted); a negative value for loc means 
no location information is Specified. The additional 
information provided by loc enables the 
Stu_$get_runtime_block entry point to return the 
runtime _ block node that corresponds to the quick PL/I 
procedure or begin block that is Sharing the designated 
Stack frame and was active at the time execution was 
interrupted. (Input) 


Entry: stu_$find_runtime_symbol 


This entry point, given a pointer to the runtime_block node that 
corresponds to a procedure or begin block, searches for the runtime_symbol node 
that corresponds to a Specified identifier name: If the name is not found in 
the given block, the parent block is searched. This is repeated until the name 
is found or the root block of the symbol structure is reached, in which case a 
null pointer is returned. 


Usage 


declare stu_$find_runtime_symbol entry (ptr, char(*) aligned, ptr, fixed 
bin) returns (ptr); 


symbol_ptr = stu_$find_symbol (block_ptr, name, found_ptr, steps); 


where: 

1 block_ptr points to the runtime_block node in which the search is to 
begin. (Input) 

2% name is the ASCII name of the runtime symbol node to be found. A 
name can be a fully or partially qualified structure name 
(e.g., "a.b.c"), ain which the runtime_symbol node that 
corresponds to the lowest level item is located. (Input) 

Be found_ptr is set to point to the runtime_block node in which the 
specified identifier is found. (Output) 

4, steps is set to the number of steps that must be taken along the 


pli_stack_frame.display_ptr chain to locate the stack_frame 
associated with the block designated by found _ptr starting 
at the stack frame for the block designated by block_ptr. 
(See "Example" below.) If the given identifier is found in 
the specified block, the value of steps is 0. (Output) 
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If the search fails, the value of steps indicates the reason 
for the failure as follows: 
-1 block_ptr is null 
-2 -more than 64 structure levels 
-3 name too long 
-4 no declaration found 
-5 symbol reference is ambiguous 
ae symbol_ptr is set to point to the runtime_symbol node if it is found or 


is null if an error occurs. (Output) 


Entry: stu_$decode_runtime_value 


This entry point is called to decode encoded values (e.g., string length or 
arithmetic precision) stored in a runtime_symbol node. 


Usage 


declare stu_$decode_runtime_value entry (fixed bin(35), ptr, ptr, ptr, ptr, 
ptr, fixed bin) returns (fixed bin(35)); 


value = stu_$decode_runtime_value (v, block _ptr, stack_ptr,  link_ptr, 
text_ptr, ref_ptr, code); 


where: 


ie V is an encoded value from a _runtime_symbol node, e.g., 
runtime _symbol.size. (Input) 


2% block_ptr points to the runtime_block node that corresponds to the 
block that contains the declaration of the identifier whose 
runtime_symbol node contains the encoded value. Normally, 
the value of block_ptr is obtained from a call to the 
stu_$find_runtime_symbol entry point described above. 
(Input) 


3% stack_ptr is a pointer to the active stack frame associated with the 
procedure or begin block that corresponds to the specified 
runtime_block node. If the specified block node is quick, 
stack_ptr should point to the stack frame in which the quick 
block is placing its automatic storage. If the specified 
block is not active and does not have a current stack frame, 
stack_ptr can be null. (Input) 


4, link ptr is a pointer to the linkage section of the specified block. 
If link _ptr is null, the stu_$decode_runtime_value entry 
point attempts to obtain the linkage pointer, if it is 
needed, from the linkage offset table (LOT); decoding fails 
if a pointer to the linkage section is needed and text_ptr, 
block_ptr, and link_ptr are all null or if the segment has 
never been executed. (Input) 
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oe text_ptr is a pointer to the base of the object segment that contains 
the Specified block. If text_ptr is null, the 


Stu_$decode_runtime_value entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame 
or the block_ptr; decoding fails if a pointer to the object 
segment is needed and stack_ptr, block_ptr, and text_ptr are 
all null. (Input) 7 


6. ref_ptr is the value of the pointer to be used as locator qualifier 
if the variable that corresponds to the runtime_symbol node 
that contains the encoded value is based. The value of 


ref_ptr can often be determined by means of the 
Stu_$get_implicit_qualifier entry point described below. 


(Input) 
Ts code . is a status code. (Output) It is: 
0 if the encoded value was successfully decoded 
1 if the value could not be decoded 
8. value is the decoded value if the value of code is 0. (Output) 


ntry: stu_$get_implicit_qualifier 


This entry point, given a pointer to the symbol node that corresponds toa 
PL/I based variable, attempts to return the value of the pointer variable that 
appeared in the based declaration (e.g., the value of "p" in "del a based 
(p);"). A null pointer is returned if the declaration does not have the proper 
form or if the value of the pointer cannot be determined. 


Usage 
declare stu_$get_implicit_qualifier entry (ptr, ptr, ptr, ptr, ptr) returns 
(ptr); 


ref_ptr = stu_$get_implicit_qualifier (block_ptr, Symbol_ptr, stack_ptr, 
link_ptr, text_ptr); 


where: 

16 block_ptr points to the runtime_block node that corresponds to the 
procedure or begin block in which the based variable is 
declared. (Input) 

ae Symbol_ptr points to the runtime_symbol node that corresponds to the 
based variable. (Input) 

3 Stack_ptr 1s a pointer to the active stack frame associated with the 


block in which the based variable is declared. If the 
specified block node is quick, stack ptr should point to the 
Stack frame in which the quick block is placing its 
automatic storage. If the specified block is not active and 
does not have a current stack frame, stack_ptr can be null. 
(Input) 
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4, link_ptr is a pointer to the linkage section of the specified block. 
If link ptr is null, the stu_$get_implicit_qualifier entry 
point attempts to obtain the linkage pointer, if it is 
needed, from the active stack frame; the implicit qualifier 
cannot be determined if a pointer to the linkage section is 
needed and stack_ptr and link_ptr are both null. (Input) 


om text_ptr is a pointer to the base of the object segment that contains 
the specified block. If text_ptr is null, the 
stu_$get_implicit_qualifier entry point attempts to obtain 
the text pointer, if it is needed, from the active stack 
frame; the implicit qualifier cannot be determined if a 
pointer to the object section is needed and stack_ptr and 
text_ptr are both null. (Input) 


6. ref_ptr dis set to the value of the implicit qualifier or is null if 
the value cannot be determined. (Output) 


Notes 


A null pointer is returned for any one of a number of reasons. Some of 
these are: 
Neg The based variable was declared without an implicit qualifier, e.g., 
del a based; 


Zs Determining the implicit qualifier involves evaluating an expression, 
for example, the based variable was declared as: 


del a based(p(i)); 
S4 The based variable was declared with an implicit qualifier, but it is 


not possible to obtain the address of the qualifier (e.g., it is an 
authentic pointer, and stack_ptr is null). 


ntry: stu_$get_runtime_address 


This entry point, given a pointer to a runtime_symbol node and information 
about the current environment of the block in which the symbol that corresponds 


to the runtime_symbol node is declared, determines the address of the specified 
variable. 
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declare stu_$get_runtime_address entry (ptr, ptr, ptr, ptr, ptr, ptr, ptr) 
returns (ptr); | 


add_ptr = 


stu_$get_runtime_address (block_ptr, Symbol_ptr, stack_ptr, 


link_ptr, text_ptr, ref_ptr, subs_ptr); 


where: 


Ts block_ptr 


2% Symbol_ptr 


3: Stack_ptr 


4, link_ptr 


ae text_ptr 


6. ref_ptr 


ie subs_ptr 


8. add_ptr 


points to the runtime_block node that corresponds to the 
block in which the symbol, whose address is to be 
determined, is declared. (Input) 


points to the runtime_symbol node that corresponds to. the 
Symbol whose address is to be determined. (Input) 


is a pointer to the active stack frame associated with the 
procedure or begin block that corresponds to the specified 
runtime_block node. If the specified block is quick, 
stack_ptr should point to the stack frame in which the quick 
block is placing its automatic storage. If the specified 
block is not active and does not have a current stack frame, 
stack_ptr can be null. (Input) 


is a pointer to the linkage section of the specified block. 
If link_ptr is null, the stu_$get_runtime_address entry 
point attempts to obtain the linkage pointer, if it is 
needed, from the LOT; the address of the specified symbol 
cannot be determined if a pointer to the linkage section is 
needed and text_ptr, block_ptr, and link_ptr are all null or 
the segment has never been executed. (Input) 


is a pointer to the base of the object segment that contains 
the specified block. If text_ptr is null, the 
stu_$get_runtime_address entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame 
or the block_ptr; the address of the specified symbol 
cannot be determined if a pointer to the object segment is 
needed and stack_ptr, block_ptr, and text_ptr are all null. 
(Input) | : 


is the value of the reference pointer to be used if the 
runtime_symbol node corresponds to a based variable. If 
ref_ptr is null, the stu_$get_runtime_address entry point 
calls the stu_$get_implicit_qualifier entry point (described 
above) to determine the value of the pointer that was used 
in the declaration of the based variable. (Input) 


points to a vector of single-precision fixed-point binary 
subscripts. The number of subscripts is assumed to match 
the number required by the declaration. This argument -can 
be null if the runtime_symbol node does not correspond to an 
array. (Input) 


is set to the full bit address (with full bit offset) of the 


variable that corresponds to the symbol node or is null if 
the address cannot be determined. (Output) 
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Entry: stu_$get_line_no 


This entry point, given a pointer to a runtime_block node and an offset in 
the text segment that corresponds to the block, determines the line number, 
starting location, and number of words in the source statement that contains the 
specified location. 


Usage 


declare stu_$get_line_no entry (ptr, fixed bin(18), fixed pbin(18), fixed 
bin(18)) returns (fixed bin(18)); 


line_no = stu_$get_line_no (block_ptr, offset, start, num); 


where: 

Vs block_ptr points to the runtime_block node that corresponds to the 
block in which the instruction offset exists. (Input) 

2. offset is the offset of an instruction in the text segment. 
(Input) 

3. start is set to the offset in the text segment of the first 
instruction generated for the source line that contains the 
specified instruction or is -1 if the line is not’ found. 
(Output) 

4, num is set to the number of words generated for the specified 
source line. (Output) 

5. line_no is set to the line number, in the main source file, of the 

| statement that contains the specified instruction or is -1 
if the specified offset does not correspond to ae statement 
in the program. (Output) 

Notes 


All line numbers refer to the main source file and not to files accessed by 
means of the Zinclude statement. 


No distinction is made between several statements that occur on the same 
source line. The start argument is the starting location of the code generated 
for the first statement on the line and num is the total length of all the 
statements on the line. t 
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Entry: Stu_$get_runtime_line_no 


This entry point, given a pointer to the Symbol header of a standard object 
Segment and an offset in the text section of the object segment, returns 
information about the line that caused the Specified instruction to be 
generated. Since the Symbol header is used to locate the statement map, this 


entry point can be used with object segments that have only a partial runtime 
Symbol table. 


Usage 


declare stu_$get_runtime_line_no entry (ptr, fixed bin(18), fixed bin(18), 
fixed bin(18), fixed bin(18)); 


call Stu_$get_runtime_line_no (head_ptr, offset, start, num, line_no); 


where: 

1. head_ptr is a pointer to the Symbol section header of a standard 
object segment. (Input) 

2. offset is the offset of an instruction in the text section. 
(Input) 

3. start is set to the offset in the text segment of the first 
instruction generated for the source line that contains the 
Specified instruction or is -1 if the line is not found. 
(Output) 

y, num is set to the number of words in the object code generated 
for the Specified source line. (Output) 

54 line_no is set to the line number, in the main source file, of the 

| Statement that contains the Specified instruction or is -1 

if the specified offset does not correspond to ae statement 
in the program. (Output) 

Notes 


All line numbers refer to the main Source file and not to files accessed by 
means of the %Zinclude Statement. 


No distinction is made between several statements that occur on the same 
Source line. The start argument is the Starting location of the code generated 
for thé first statement on the line and num is the total length of all the 
Statements on the line. 
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Entry: stu_$get_location 


This entry point, given a pointer to a runtime_block node and_ the line 
number of a source’ statement in the block, returns the location in the text 
segment of the first instruction generated by the specified source line. 


Usage 


declare stu_$get_location entry (ptr, fixed bin(18)) returns (fixed 
bin(18)); 


offset = stu_$get_location (block_ptr, line_no); 


where: 

Ig block_ptr points to the runtime_block node. (Input) 

2. line_no | specifies the source line number, which must be in the main 
source file. (Input) | 

3. offset is set to the offset in the text segment of the first 


instruction generated for the given line or is -1 if no 
instructions are generated for the given line. (Output) 


Entry: stu_$get_line 


This entry point, given a pointer to the symbol header of a standard object 
segment and an offset in the text section of the object segment, returns 
information that allows the source line that generated the specified location to 
be accessed. This entry point can be used with programs that have only a 
partial runtime symbol table. 


Usage 
declare stu_$get_line entry (ptr, fixed bin(18), fixed bin, fixed bin(18), 
fixed bin(18), fixed bin, fixed bin); 


call stu_$get_line (head_ptr, offset, n_stms, line_no, line_offset, 
line_length, file); 


where: 

1% head_ptr is a pointer to the symbol section header of ae standard 
object segment. (Input) 

2. offset is the offset of an instruction in the text’ section. 


(Input) 
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35s n_stms indicates the number of source Statements about which 
information is desired; the string specified by file, 
line_offset, and line_length is the source for n_stms 
Statements, Starting with the statement that contains the 
given instruction. (Input) 


4, line_no is set to the line number, in the file in which it is 
contained, of the statement that contains the Specified 
instruction or is -1 if the given offset does not correspond 
to a statement in the object program. (Output) 


oe line_offset is set to the number of characters that precede the first 
character of the source for. the Specified statement. 
(Output) 

6. line_length is set to the number of characters occupied by the n_stms 


Statements that start with the Statement that contains the 
Specified location; the source for these statements is 
assumed to be entirely contained within a single source 
file. Let S be the contents of the source file that 
contains the specified statements considered as a single 
String; then the source String for the n_stms statements is 
substr(S,line_offset+1,line_length). (Output) 


T% file is the number of the source file in which the source for the 


desired statements is contained (see "Source Map" in 
Section I of this manual). (Output) 


Entry: stu_$get_runtime_location 


This entry point, given a pointer to the symbol header of a standard object 
segment and a line number in the main source file, returns the starting location 
in the text section of the object code generated for the line. This entry point 
can be used with object segments that have Only a partial runtime symbol table. 


Usage 


declare riaysect_runtime_location entry (ptr, fixed bin) returns (fixed 
bin(18)); 


offset = Stu_$get_runtime_location (head_ptr, line_no); 


where: 
Ig head_ptr is a pointer to the Symbol section header of a= standard 
object segment. (Input) 
2. line_no is the line number of a statement in the main source file. 
(Input) 
33 offset is set to the location in the text Segment where the object 


code generated for the specified line begins or is -1 if no 
code is generated for the given line. (Output) 
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Entry: stu_$get_statement_map 


This entry point, given a pointer to the symbol header of a standard object 
segment, returns information about the statement map of the object segment. 
This entry point can be used with object segments that have only a partial 
runtime symbol table. 


Usage 


declare stu_$get_statement_map entry (ptr, ptr, ptr, fixed bin); 


call stu_$get_statement_map (head_ptr, first_ptr, last ptr, map_size); 


where: 

hs head_ptr is a pointer to the symbol section header of a standard 
object segment. (Input) 

es first_ptr is set to point to the first entry in the statement map of 
the object segment or is null if the object segment does not 
have a statement map. (Output) 

ce last_ptr is set to point to the location following the last entry in 
the statement map of the object segment or is null if the 
object segment does not have a statement map. (Output) 

4, map_size is set to the number of words in an entry in the statement 


map. (Output) 


ntry: stu_$offset_to_pointer 


This entry point attempts to convert an offset variable to a pointer value 
using the area, if any, on which the offset was declared. 


Usage 
declare stu_$offset_to_pointer entry (ptr, ptr, ptr, ptr, ptr, ptr) returns 
(ptr); | 
off_ptr = stu_$offset_to_pointer (block_ptr, symbol_ptr, data_ptr, 


stack_ptr, link_ptr, text_ptr); 


where: 


As block_ptr points to the runtime_block node that corresponds to the 

| procedure or begin block in which the offset variable is 
declared. (Input) 

2. symbol_ptr points to the runtime_symbol node that corresponds to the 


offset variable. (Input) 
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3 data_ptr points to the offset value to be converted to a pointer. 
(Input) 
4, Stack_ptr is a pointer to the active stack frame associated with the 


block in which the offset variable is declared. If the 
Specified block node is quick, stack_ptr should point to the 
Stack frame in which the quick block is placing its 
automatic storage. If the Specified block is not active and 
does not have a current stack frame, stack_ptr can be null. 
(Input) 


Dis link_ptr is a pointer to the linkage section of the specified block. 
If link_ptr is null, the stu_$offset_to_pointer entry point 
attempts-to obtain the linkage pointer, if it is needed, 
from the stack frame; conversion fails if a pointer to the 
linkage section is needed and Stack_ptr and link_ptr are 
both null. (Input) 


6. text_ptr is a pointer to the base of the object segment that contains 
the specified block. If text_ptr is null, the 
stu_$offset_to_pointer entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame; 
conversion fails if a pointer to the text section is needed 
and stack_ptr and link_ptr are both null. (Input) 

Te off_ptr is set to the pointer value that corresponds to the offset 


value; it is null if the conversion fails or if the offset 
value is itself null. (Output) 


ntry: stu_$pointer_to_offset 


This entry point attempts to convert a pointer value to an offset variable 
uSing the area, if any, on which the offset was declared. 


Usage 


declare stu_$pointer_to_offset entry (ptr, ptr, ptr, ptr, ptr, ptr) returns 
(offset); 


off_val = stu_$pointer_to_offset (block_ptr, symbol_ptr, data_ptr, 
Stack_ptr, link_ptr, text_ptr); 
where: 
1; block_ptr is as above. (Input) 
2% Symbol_ptr is as above. (Input) 


ce data_ptr points at the pointer value to be converted to an offset. This 
pointer value must be an unpacked pointer value. (Input) 


y, stack_ptr is as above. (Input) 


5. link_ptr is as above. (Input) 
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6. text ptr is as above. (Input) 
Ts off_val is set to the offset value that corresponds 
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the pointer 


value; it is null if the conversion fails or if the pointer 


value is itself null. (Output) 


Entry: stu_$remote_format 


This entry point decodes a remote format specification. 


Usage 


declare stu_$remote_format entry (fixed bin(35), ptr, ptr, label) returns 


(fixed bin); 


code = stu_$remote_format (value, stack_ptr, ref_ptr, format); 


where: 
1. © value is the remote format value to be decoded. (Input) 
rae stack_ptr is a pointer to the active stack frame of the block that 
- eontains the format being decoded. (Input) | 
3 ref_ptr is the pointer value to be used if the format value being 
decoded requires pointer qualification. (Input) 
4. format is set to the format value if decoding is successful. 
(Output) 
5. code is a status code. (Output) It is: 
0 3 if decoding is successful 
1 if decoding is not successful 
Example 


The use of some of the entry points documented above is illustrated by the 


following sample program, which is called with: 


stack _ptr a pointer to the stack frame of a PL/I block 


symbol an ASCII string giving the name of a user’ symbol 


program 


subs_ptr a pointer to an array of binary integers that 
values 
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procedure determines the address and Size of the specified Symbol. If 


any errors occur, the returned address is null. 


example: 


declare 


declare 


proc (stack_ptr, Symbol, subs_ptr, size) returns (ptr); 


Stack_ptr ptr, 


symbol char(*) aligned, 
Subs_ptr ptr, 
size fixed bin(35); 


(header_ptr, block_ptr, Symbol_ptr, ref_ptr, Sp, blk_ptr, 
Stack_ptr, add_ptr) ptr, 

(i, steps) fixed bin, 

code fixed bin(35), 

stu_$get_runtime_block entry(ptr, ptr, ptr, fixed bin(18)), 
Stu_$find_runtime_symbol entry(ptr,char(#) aligned,ptr,fixed bin) 
returns(ptr), , 

Stu_$get_runtime_address entry(ptr,ptr,ptr,ptr, ptr, ptr, ptr) 
returns(ptr), 

Stu_$decode_runtime value entry(fixed bin(35),ptr,ptr,ptr,ptr, ptr, 


fixed bin) returns(fixed bin(35)); 


Zinclude pli1_stack_frame; 
Zinclude runtime_symbol; 


/* determine header and block pointers */ 


call stu_$get_runtime_block(stack_ptr,header_ptr,block_ptr,-1); 
if block_ptr = null then return(null); 

/* search for specified Symbol */ 

Symbol_ptr = stu_$find_runtime_symbol(block_ptr,symbol,blk_ptr,steps); 
if symbol_ptr = null then return(null); 

/* determine stack frame of block owning symbol */ 

Sstack_ptr; 

= 1 to steps; 

Sp = sp => pli_stack_frame.display_ptr; 

end; 

/* determine address of Symbol #*/ 

ref_ptr null; 


add_ptr stu_$get_runtime_address(blk_ptr,symbol_ptr,sp,null,null, 
ref_ptr,subs_ptr); 


if add_ptr = null then return(null); 
/* determine size */ 


Size = symbol_ptr -> runtime_symbol.size; 
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if size < 0 
then do; 
size = stu_$decode_runtime_value(size,blk_ptr,sp,null,null, 
ref_ptr,code); 
if code “= 0 then return(null); 
end; 


return(add_ptr); 
end example; 
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Name: sub_err_ 


The sub_err_ subroutine is called by other programs that wish to report an 
unexpected situation without usurping the calling environment's responsibility 
for the content of and disposition of the error message and the choice of what 
to do next. The caller specifies an identifying message and may specify a 
status code. Switches that describe whether and how to continue execution and a 
pointer to further information may also be passed to this subroutine. The 
environment that invoked the subroutine caller of sub_err_ may intercept and 
modify the standard system action taken when this subroutine is called. 


General purpose subsystems or subroutines, which can be called in a variety 
of I/O and error handling environments, should report the errors they detect by 
calling the sub_err_ subroutine. 


Usage 


rd 


declare sub_err_ entry options (variable) ; 


call sub_err_ (code, name, flags, info_ptr, retval, ctl string, ioa_args); 


where: 


1. code is a standard system status code (declared fixed bin(35)) 
describing the reason for calling the sub_err_ subroutine. 
(Input) 


2. name is the name (declared as a nonvarying character string) of the 
subsystem or module on whose behalf the sub_err_ subroutine is 
called. (Input) 


3% flags describe how and whether restart may be attempted. The flags 

argument should be declared as a nonvarying character string. 

(Input) One of the following values is permitted: 

h halt at command level after printing message; resume if 
start command is invoked (described in the MPM Commands). 

ec continue after printing message. 

Ss stop; attempt to restart raises the illegal_return 
condition. 


4, info_ptr is a pointer (declared as an aligned pointer) to optional 
information specific to the situation. The standard system 
environment does not use this pointer, but it is provided for 
the convenience of other environments. (Input) 


or retval is a return value from the environment to which the error was 
reported. The standard system environment sets this value to 
zero. Other environments may set the retval argument to other 
values, which may be used to select recovery strategies. fhe 
retval argument should be declared fixed bin(35). 
(Input/Output) 
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0 etl_string is an ioa_ format control String (declared as a nonvarying 
character string) that defines the message associated with the 
call to the sub_err_ subroutine. Consult the description of 
the ioa_ subroutine in the MPM Subroutines. (Input) 

1 ioa_args are any arguments required for conversion by the ctl_string 
argument. (Input) 

Operation 


. The sub_err_ subroutine Proceeds as follows: the structure described below 
is filled in from the arguments to the sub_err_ subroutine and Signal_ is called 
to raise the sub_error_ condition. 


When the standard system environment receives a sub_error_ Signal, it 
prints a message of the form: | | 


name error by sub_name]}location 
Status code message. Message from ctl_string. 


The standard environment then sets retval to zero and returns, if the value 
Cc is specified; otherwise it calls the listener. If the start command is 
invoked, the standard environment returns to Sub_err_, which returns to the 
subroutine caller of the Sublerr_ subroutine unless s is Specified. If the 
value s is specified, the Sub_err_ subroutine signals the illegal_return 
condition. 


Handler Operation 


All handlers for the any_other condition must either pass’ the sub_error_ 
condition on to another handler, or else must handle the condition correctly. 
Correct handling consists of printing the error message and of respecting the 
cant_restart and default_restart flags, unless’ the environment deliberately 
countermands these actions (for example, for debugging purposes). | 


If an application program wishes to call a Subsystem that reports errors by 
the sub_err_ subroutine and wishes to replace the standard system action for 
some classes of sub_err_ subroutine calls, the application should establish a 
handler for the sub_error_ condition by a PL/I on statement. When the handler 
is activated as a result of a call to the Sub_err_ subroutine by some dynamic 
descendant, the handler should call the find_condition_info_ subroutine to 
obtain the software_info_ptr that points to a structure with the following 
declaration. 
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del 1 info aligned based (software_info_ptr), 
2 length fixed bin, 
2 version fixed bin, 
2 action_flags aligned, 
3 cant_restart bit(1) unal, 
3 default_restart bit(1) unal, 
3 pad bit(34) unal, 
2 info_string char(256) varying, 
2 code fixed bin(35), 
2 retval fixed bin(35), 
2 name char(32), 
2 info_ptr ptr’: 
where: 
1. length is the size of the structure in words. 
2. version is the version number of the structure. Currently, the 
version is 2. 
oe cant_restart indicates if the condition cannot be restarted. 
Wq1th yes 
NONh no 
4, default_restart indicates if the standard environment prints the message 
and continues execution without calling the listener. 
qth yes 
"OMh no 
5. pad is padding. 
6. info _string is the converted message from the ctl_string and ioa_args 
arguments. 
7. code is a standard system status code. 
8. retval is the return value. The standard environment sets this 


value to zero. 
9. name | is the name of the module encountering the condition. 


10. info_ptr is a pointer to additional information associated with the 
condition. 


The handler should check info.name and info.code to make sure that this 
particular call to the sub_err_ subroutine is the one desired and, if not, call 
the continue_to_signal_ subroutine. If the handler determines that it wishes to 
intercept this case of the sub_error._ condition, the information structure 
provides the message as converted, switches, ete. If control returns to the 
sub_err_ subroutine, any change made to the value of info.retval is returned to 
the caller of this subroutine. 
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Name: sys_info 
The Ssys_info data base is a Wired-down, per-system data base. It is 
accessible in all rings but can be modified only in ring 0. It contains many 
System parameters and constants. All references to it are made through 
externally defined variables. 
Usage 
del ( sys_info$clock_ fixed bin, 
1 sys_info$ips_mask_data aligned, | 
2 count fixed bin, 
2 array: (4 refer(count)), 

3 mask bit(35) aligned, 

3 name char(4) aligned, 
sys_info$page_size fixed bin(35), 
sys_info$max_seg_size fixed bin(35), 
sys_info$default_stack_length fixed bin(35), 
sys_info$access_class_ceiling bit(22), 
sys_info$time_correction_constant fixed bin(71), 
sys_info$maxlinks fixed bin, 
sys_info$time_delta fixed bin, 
sys_info$time_of_bootload fixed bin(71), 
sys_info$time_zone char(3)) external; 

where: 
1. clock_ is the port number of the system controller 
containing the clock. 
2. ips_mask_data is the array that specifies the number and 
mapping of interprocess signal (IPS) masks. 


"count" is the current number of valid IPS names 


count 


array 


page_size 

max_seg_ size 
default_stack_length 
access_class_ceiling 


time_correction_constant 
maxlinks 


time_delta 


and "array" specifies the mapping between IPS 
name and IPS mask for each IPS signal. 

is the current number of valid IPS names. 
Specifies the mapping between IPS name and IPS 


mask for each IPS signal. 


is the page size in words. 

is the maximum segment size in words. 

is the default stack maximum size in words. 

is the maximum access class. 

is the soRneetion from Greenwich mean time (GMT) 
in microseconds. 


is the maximum depth to which the system chases 


a link without finding a branch. 
is the difference between this time zone and GMT 
in hours. 
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12. time_of_bootload is the clock reading at the time of bootload. 


13. time_zone is the name of the time zone (e.g., EST). 
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Name: system_info_ 


The system_info_ subroutine allows the user to obtain information 


concerning system parameters. All entry points that accept more than one 
argument count their arguments and only return values for the number of 
arguments’ given. Certain arguments, such as the price arrays, must. be 


dimensioned as shown. 


Entry: system_info_$installation_id 


This entry point returns the 32-character installation identifier typed in 
the header of the who command (described in the MPM Commands) and at dial-up 
time. 


Usage 


declare system_info_$installation_id entry (char(*)); 


call system_info_$installation_id (id); 


where id is the installation identifier. (Output) 


Entry: system_info_$sysid 


This entry point returns the eight-character system identifier typed in the 
header of the who command and at dial-up time. 


Usage 


declare system_info_$sysid entry (char(*)); 


call system_info_$sysid (sys); 


where sys is the system identifier that identifies the current version of the 
system. (Output) 


Entry: system_info_$titles 


This entry point returns several character strings that more formally 
identify the installation. 
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Usage 


declare system_info_$titles entry (char(*), char(*), char(*), char(*)); 


system_info_ 


call system_info_$titles (c, d, ec, dd); 


where: 


Tis Cc 
2. d 
3. eXe) 
4. 6 odd 


is the company or institution name (a maximum of 
characters). (Output) 


is the department or division name (a maximum of 
characters). (Output) 


is the company name, double spaced (a maximum of 
characters). (Output) | 


is the department name, double spaced (a maximum of 
characters). (Output) | a 


Entry: -system_info_$users 


Usage 


declare system_i 
bin);. 


eall system_info_$users (mn, nn, mu, nu); 


where: 

1. mn 
oe inn 
33 mu 
4. nu 


is the maximum number of users. (Output) 


is the current number of users. (Output) 


is the maximum number of load units (times 10). (Output) 


is the current number of load units (times 10). (Output) 


Entry: system_info_$timeup 


64 
64 
120 


120 


| This entry point returns the current and maximum number of load units and 
users. | 7 | 


nfo_gusers entry (fixed bin, fixed bin, fixed bin, fixed 


This entry point returns the time at which the system was last started up. 
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Usage 


declare system_info_$timeup entry (fixed bin(71)); 


call system_info_$timeup (tu); 


where tu is the time the system came up. (Output) 


ntry: system_info_$next_shutdown 


This entry point returns the time of the next scheduled shutdown, the 
ere is the shutdown, and the time the System will return, if this data is 
available. 


Usage 


declare a Lt entry (fixed bin(71), char(*), fixed 
bin(71)); 


call system_info_$next_shutdown (td, rsn, tn); 


where: 
ee td is the time of the next scheduled shutdown. If none is 
scheduled, this is 0. (Output) 
2% rsn is the reason for the next shutdown (a maximum of 32 
; characters). If it is not known, it is blank. (Output) 
3. tn is the time the system will return. If it is not known, it is 


O. (Output) 


ntry: system_info_$prices 


This entry point returns the per-shift prices for interactive use. 


7-144 AK92 


system_info_ system_info_ 


Usage 


declare system_info_$prices entry ((0:7) float bin, (0:7) float bin, (0:7) 
float bin, (0:7) float bin, float bin, float bin); 


call system_info_$prices (cpu, log, pre, cor, dsk, reg); 


where: 

“ie cpu is the CPU-hour rate per shift. (Output) 

2 log is the connect-hour rate per shift. (Output) 

3 pre is the process-hour rate per shift. (Output) 

4, cor is the page-second rate for main memory per shift. (Output) 
5 dsk © is the page-second rate for secondary storage. (Output) 

6 


. reg is the registration fee per user per month. (Output) 


Entry: system_info_$device_prices 


This entry point returns the per-shift prices for system device usage. 


Usage 


declare system_info_$device_prices entry (fixed bin, ptr); 


call system_info_$device_prices (ndev, dev_ptr);. 


where; 
15 ndev is the number of devices with prices. (Output) 
2. dev_ptr - points to an array where device prices are stored. (Input) 
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In the above entry point, the user must provide the following array (in his 
Storage) for device prices: | | 


del 1 dvt(16) based (devp) aligned, 

2 device_id char(8), 

2 device_price (0:7) float bin; 
where; 
Te dvt is the user structure. Only the first ndev of the 16 will be 

filled in. 

25 device_id is the name of the device. 
3% device_price is the per-hour price by shifts for the device. 


Entry: system_info_$shift_table 


This entry point returns a table that defines when each shift begins and 
ends. 


‘Usage 


declare system_info_$shift_table entry ((336) fixed bin); 


call system_info_$shift_table (st); 


where st is a table with one entry for each half hour, beginning with 0000 
Monday. The table gives the shift number for that half-hour period. Shifts can 
be from 0 to 7. (Output) 


ntry: system_info_$abs_prices 


This entry point returns the prices for CPU and real time for each absentee 
queue. 
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Usage 
declare system_info_$abs_prices entry ((4) float bin, (4) float bin); 


call system_info. $abs_prices (ecpurate, realrate); 


where: 
1. cpurate is the price per CPU hour for absentee queues 1 to 4. (Output) 
2. realrate is the memory unit rate for absentee queues 1 to 4. (Output) 


Entry: system_info_$io_prices 


This entry point returns the prices for unit processing for each I/0 daemon 
queue. 


Usage 


declare system_info_$io_prices entry ((4) float bin); 


call system_info_$io_prices (rp); 


where rp is the price per 1000 units (a unit is 700 bits) for each I/O daemon 
queue. (Output) 


Entry: system_info_$last_shutdown 


This entry point returns the clock time of the last shutdown or crash and 
an eight-character string giving the ERF (error report form) number of the last 
crash (blank if the last shutdown was not a crash). 


Usage 


declare system_info_$last_shutdown entry (fixed bin(71), char(*)); 


call system_info_$last_shutdown (time, erfno); 


where: 
1. time is the clock time of the last shutdown. (Output) 
2. erfno is the ERF number of the last crash, or blank. (Output) 
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Entry: System_info_$access_ceiling 


This entry point returns the System_high access authorization or class. 


Usage 


declare system_info_$access_ceiling entry (bit(72) aligned); 


call system_info_$access_ceiling (ceil); 


where ceil is the access ceiling. (Output) 


Entry: system_info_$level_names 


This entry point returns the 32-character long names and eight-character 
Short names for sensitivity levels. 


Usage 


declare system_info_$level_names entry (dim(0:7) char(32), dim(0:7) 
char(8)); 


call system_info_$level_names (long, short); 


where: 
13 long is an array of the long level names. (Output) 
2% short is an array of the short level names. (Output) 


ntry: system_info_$category_names 


This entry point returns the 32-character long names and the 
eight-character short names for the access categories. 
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sage 
declare system_info_$category_names entry (dim(18) char(32), dim(18) 
char(8)); 


call system_info_$category_names (long, short); 


where long and short are the same as for the system_info_$level_names entry 
point. 3 
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Name: timer_manager_ 


The timer_manager_ Subroutine allows many CPU usage timers and real-time 
timers to be used Simultaneously by a process. The caller can specify for each 
timer whether a wakeup is to be issued or a Specified procedure is to be called 
when the timer goes off. 


_The timer_manager_ subroutine fulfills a specialized need of certain 
sophisticated programs. A user_ should be familiar with interprocess 
communication in Multics and the pitfalls of writing programs that can run 
asynchronously within a process. These pitfalls can be avoided by using only 
the timer_manager_$sleep entry point. 


For most uses of the timer_manager_ subroutine, a cleanup condition 
handler, which resets all the timers that might be set by a software Subsysten, 
Should be set up. If the subsystem is aborted and released, any timers set up 
by the subsystem can be reset instead of going off at undesired times. | 


| To be used, the timer_manager_ subroutine must be established as the 
condition handler for the conditions alrm and cput. This is done automatically 
by the standard Multics environment. 


Gen rgumen 


At least one of the following arguments is called in all of the 
timer_manager_ entry points. For convenience, these common arguments are 
described below rather than in each entry point description. 


1% channel is the name of the event channel (fixed binary(71)) over 
which a wakeup is desired. Two or more timers can be 
running simultaneously, all of which may, if desired, issue 
a wakeup on the same event channel. 


2. routine is a procedure entry point that is called when the timer 
goes off. The routine is called as follows: 


declare routine entry (ptr, char(*)); 


call routine (mc_ptr, name); 


where; 

mc_ptr is a pointer to a structure containing the 
machine conditions at the time of the process 
interrupt. (Input) 

name is the condition name: alrm for aeereal-time 


timer and cput for a CPU timer. (Input) 


(See the signal_ subroutine for a full description of the 
mc_ptr and name arguments.) Two or more timers can be 
running simultaneously, all of which may, if desired, call 
the same routine. 


7-150 AK92 


, ae 
eens ER EEN TRE 


timer_manager_ | timer_manager_ 

3. time | is the time (fixed binary(71)) at which the wakeup or call 
is desired. 

4, flags is a 2-bit string (bit(2)) that determines how time is to be 


interpreted. The high-order bit indicates whether it is an 
absolute or a relative time. The low-order bit indicates 
whether it is in units of seconds or microseconds. Absolute 
real time is time since January 1, 1901, 0000 hours 
Greenwich mean time, i.e., the time returned by the clock_ 
subroutine (described in the MPM Subroutines). Absolute CPU 
time is total virtual time used by the the process, i.e., 
the time returned by the cpu_time_and_paging. subroutine 
(described in the MPM Subroutines). Relative time begins 
when the timer_manager_ subroutine is called. 


"11"b means relative seconds 
"10" b means relative microseconds 
"O1"b means absolute seconds 
"O0O"b means absolute microseconds 


Entry: timer_manager_$sleep 


This entry point causes the process to go blocked for a period of real 
time. Other timers that are active continue to be processed whenever they go 
off; however, this routine does not return until the real time has been passed. 


Usage 


declare timer_manager_$sleep entry (fixed bin(71), bit(2)); 


call timer_manager_$sleep (time, flags); 


The time is always real time; however, it can be relative or absolute, 
seconds or microseconds, as explained above in "Generic Arguments." 


Entry: timer_manager_$alarm_call 


This entry point sets up a real-time timer that calls the routine specified 
when the timer goes off. 


Usage 


declare timer_manager_$alarm_call entry (fixed bin(71), bit(2), entry); 


call timer_manager_$alarm_call (time, flags, routine); 
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Entry: timer_manager_$alarm_call_inhibit 


This entry point sets up a real-time timer that calls the handler routine 
Specified when the timer goes off while all interrupts are inhibited. When the 
handler routine returns from the interrupt, interrupts are reenabled. If the 
handler routine does not return from the interrupt, interrupts are not reenabled 
and the user process may malfunction. | 


Usage 


declare rue manager_$alarm_call_inhibit entry (fixed bin(71), bit(2), 
entry); | 


call timer_manager_$alarm_call_inhibit (time, flags, routine); 


Entry: timer_manager_$alarm_wakeup 


| This entry point sets up a real-time timer that issues a wakeup on the 
event channel specified when the timer goes off. The event message passed is 
the string “alarm __", (See the ipce_ subroutine for a discussion of event 
channels. ) 


Usage 
declare timer_manager_$alarm_wakeup entry (fixed bin(71), bit(2), fixed 
bin(71)); 


call timer_manager_$alarm_wakeup (time, flags, channel); 


Entry: timer_manager_$cpu_call 


This entry point sets up a CPU timer that calls the routine specified when 
the timer goes off. 


Usage 


declare timer_manager_$cpu_call entry (fixed bin(71), bit(2), entry); 


call timer_manager_$cpu_call (time, flags, routine); 
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Entry: timer_manager_$cpu_call_inhibit 


This entry point sets up a CPU timer that calls the handler routine 
specified with all interrupts inhibited when the timer goes off. When the 
handler routine returns from the interrupt, interrupts are reenabled. If the 
handler routine does not return from the interrupt, interrupts are not reenabled 
and the user process may malfunction. 


Usage 
declare timer. manager_$cpu_call_inhibit entry (fixed bin(71), bit(2), 
entry); 
call timer_manager_$cpu_call_inhibit (time, flags, routine); 


Entry: timer_manager_$cpu_wakeup 


This entry point sets up a CPU timer that issues a wakeup on the event 
channel specified when the timer goes off. The event message passed is the 
string "cpu_time". 


Usage 
declare timer_manager_$cpu_wakeup entry (fixed bin(71), bit(2), fixed 
bin(71)); 
call timer_manager_$cpu_wakeup (time, flags, channel); 


Entry: timer_manager_$reset_cpu_call 


This entry point turns off all CPU timers that call the routine specified 
when they go off. 


Usage 


declare timer_manager_$reset_cpu_call entry (entry); 
call timer_manager_$reset_cpu_call (routine); 
Entry: timer_manager_$reset_cpu_wakeup 


This entry point turns off all CPU timers that issue a wakeup on the event 
channel specified when they go off. 


7-153 AK92 


IL SSSSS~SCS COC LT a ee a aera aereaeaeceacaccaraaae eames, 
te ene cee eneenennavenecntnneneneenmnemnnnenemnaennneses 


ea a 
timer_manager_ timer_manager_ 
eee tebe 2 
Usage wi 
declare timer_manager_$reset_cpu_wakeup entry (fixed bin(71)); 
call timer_manager_$reset_cpu_wakeup (channel); 
Entry: timer_manager_$reset_alarm_call 
This entry point turns off all real-time timers that call the routine 
Specified when they go off. 
Usage 
declare timer_manager_$reset_alarm_call entry (entry); 
call timer_manager_$reset_alarm_call (routine); 
Entry: timer_manager_$reset_alarm_wakeup 
This entry point turns off all real-time timers that issue a wakeup on the | 


event channel specified when they go off. 


Usage . 


declare timer_manager_$reset_alarm_wakeup entry (fixed bin(71)); 


call timer_manager_$reset_alarm_wakeup . (channel) ; 
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Name: tssi_ 


The tssi_ (translator storage system interface) subroutine simplifies the 
way the language translators use the storage system. The tssi_$get_segment and 
tssi_$get_file entry points prepare a segment or multisegment file for use as 
output from the translator, creating it if necessary, truncating it, and setting 
the access control list (ACL) to rw for the current user. The 
tssi_$finish_segment and tssi_$finish_file entry points set the bit counts of 
segments or multisegment files, make them unknown, and put the proper ACL on 
them. The tssi_$clean_up_segment and tssi_$clean_up_file entry points are used 
by cleanup procedures in the translator (on segments and multisegment files 
respectively). | 


Entry: tssi_$get_segment 


This entry point returns a pointer to a specified segment. The ACL on the 
segment is rw for the current user. If an ACL must be replaced to do this, 
aclinfo_ptr is returned pointing to information to be used in resetting the ACL. 


Usage 


declare tssi_$get_segment entry (char(*), char(*), ptr, ptr, fixed 
bin(35)); 


call tssi_$get_segment (dir_name, entryname, seg_ptr, aclinfo_ptr, code); 


where:. 

lig dir_name is the pathname of the containing directory. (Input) 

2. entryname is the entryname of the segment. (Input) 

3% seg_ptr is a pointer to the segment, or is null if an error is 
encountered. (Output) 

4, aclinfo_ptr is a pointer to ACL information (if any) needed by the 
tssi_$finish_segment entry point. (Output) 

5. code is a storage system status code. (Output) 


Entry: tssi_$get_file 


This entry point is the multisegment file version of the tssi_$get_segment 
entry point. It returns a pointer to the specified file. Additional 
components, if necessary, can be accessed using the msf_manager_$get_ptr entry 
point (see the description of the msf_manager_ subroutine in this document), 
with the original segment considered as component OQ. 
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Usage 


declare tssi_$get_file entry (char(*), char(*), ptr, ptr, ptr, fixed 


bin(35)); 
call tssi_$get_file (dir_name, entryname, seg ptr, aclinfo_ptr, fceb_ptr, 

code); 

where: 

ig dir_name is the pathname of the containing directory. (Input) 

age entryname is the entryname of the multisegment file. (Input) 

3% seg _ ptr is a pointer to component O of the file. (Output) 

4, aclinfo_ptr is a pointer to ACL information (if any) needed by the 


tssi_$finish_file entry point. (Output) 


ome feb_ptr is a pointer to the file control block needed by the 
msf_manager_ subroutine. (Output) 


6. code is a storage system status code. (Output) 


Entry: tssi_$finish_segment 


This entry point sets the bit count on the segment after the translator is 
finished with it. It also terminates the segment. The ACL is reset to the way 
it was before the tssi_$get_segment entry point was called. If no ACL existed 
for the current user, the mode is set to "mode" for the current user. 


Usage 


declare tssi_$finish_segment entry (ptr, fixed bin(24), bit(36) aligned, 
ptr, fixed bin(35)); 


call tssi_$finish_segment (seg_ptr, bce, mode, aclinfo_ptr, code); 


where: 

1. seg _ptr is a pointer to the segment. (Input) 

2 be | is the bit count of the segment. (Input) 

$4 mode is the seeene mode to be put on the segment. (Input) 


"110"b re access 
"101"b rw access 


4, aclinfo_ptr is a pointer to the saved ACL information returned by the 
tssi_$get_segment entry point. (Input) 


5. code is a storage system status code. (Output) 
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Entry: tssi_$finish_file 


This entry point is the same as the tssi_$finish_segment entry point, 
except that it works on multisegment files, and closes the file, freeing the 
file control block. 


Usage 


declare tssi_$finish_file entry (ptr, fixed bin, fixed bin(24), bit(36) 
aligned, ptr, fixed bin(35)); 


call tssi_$finish_file (feb_ptr, component, be, mode, aclinfo_ptr, code); 


where: 

Vs feb_ptr is a pointer to the file control block returned by _ the 
tssi_$get_file entry point. (Input) 

2% component is the highest-numbered component in the file. (Input) 

3. be is the bit count of the highest-numbered component. (Input) 

4, mode is the access mode to be put on the multisegment file. (Input) 

Dis aclinfo_ptr is a pointer to the saved ACL information returned by the 


tssi_$get_file entry point. (Input) 


6. code is a storage system status code. (Output) 


Entry: tssi_$clean_up_segment 


Programs that use the tssi_ subroutine must establish a cleanup procedure 
that calls this entry point. (For a discussion of cleanup procedures” see 
"Nonlocal Transfers and Cleanup Procedures" in Section VI of the MPM Reference 
Guide.) If more than one call is made to the tssi_$get_segment entry point, the 
cleanup procedure must make the appropriate call to the tssi_$clean_up_segment 
entry point for each aclinfo_ptr. 


The purpose of this call is to free the storage that the tssi_$get_segment 
entry point allocated to save the old ACLs of the segments being translated. It 
is to be used in case the translation is aborted (e.g., by a quit signal). 
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Usage 


declare tssi_$clean_up_segment entry (ptr); 
call tssi_$clean_up_segment (aclinfo_ptr); 


where aclinfo_ptr is a pointer to the saved ACL information returned by the 
tssi_$get_segment entry point. (Input) : 


Entry: tssi_$clean_up_ file 


This entry point is the cleanup entry point for multisegment files. In 
addition to freeing ACLs, it. closes the file, freeing the file control block. 


Usage 


declare tssi_$clean_up file entry (ptr, ptr); 


call tssi_$clean_up_file (feb_ptr, aclinfo_ptr); 


where: 


ie feb_ptr is a pointer to the file control block returned by the 
tssi_$get_file entry point. (Input) 


ae aclinfo_ptr is a pointer to the saved ACL information returned by the 
tssi_$get_segment entry point. (Input) 
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Name: tty_ 


The control operations described below can be used to change various 
aspects of the behavior of the user's terminal. For a description of the more 
commonly used control operations, as well as other types of operation supported 
by the tty_ 1/0 module, see the description of the module in MPM Subroutines. 


For the control operations described below whose names begin with "set", 
with the exception of set_editing_chars, the ring 0 typewriter DIM does not copy 
the user's table, but simply copies the pointer supplied by the user. The user 
must therefore neither destroy nor modify such a table after making one of these 
calls. | 


set_delay , 
sets the numbers of delay characters associated with the output of 
carriage-motion characters. The info_ptr points to the following 
structure: 
del 1 delay based aligned, 
2 version fixed bin, 
2 default fixed bin, 
2 vert_nl fixed bin, 
2 horz_nl float bin, 
2 const_tab fixed bin, 
2 var_tab float bin, 
2 backspace fixed bin, 
2 vt_ff fixed bin; 
where: 
version is the version number of the structure. It must be 
default indicates, if nonzero, that the default values for 
the current terminal type and baud rate are to be 
used. If it is not zero, the remainder of the 
structure is ignored. 
vert_nl is the number of delay characters to be output for 
all newlines to allow for the linefeed. If it is 
negative, it is the complement of the minimum number 
of characters that must be transmitted between two 
linefeeds (for a device such as a GE TermiNet 1200). 
horz_nl is a number to be multiplied by the column position 
to obtain the number of delays to be added for the 
carriage-return portion of a newline. The formula 
for calculating the number of delay characters to be 
output following a newline is: . 
ndelays = vert_nl + fixed (horz_nl*column) 
const_tab is the constant portion of the number of delays 


associated with any horizontal tab character. 
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var_tab is the number of additional delays associated with a 


horizontal tab for each column traversed. The 
formula for calculating the number of delays to be 
output following a horizontal tab is: 


ndelays = const_tab + fixed (var_tab¥*n_columns) 


backspace is the number of delays to be output following a 


backspace character. If it is negative, it is the 
complement of the number of delays to be output with 
the first backspace of a series only (or a single 
backspace). This is for terminals such as the 
GE TermiNet 300 which need delays to allow for hammer 
recovery in case of overstrikes, but do not require 
delays for the carriage motion associated with the 
backspace itself. 


vt_ff - is the number of delays to be output following a 


is 


vertical tab or formfeed. 


used to find out what delay values are currently in effect. The 


info_ptr points to the structure described for set_delay (above), 


which 


is filled in as a result of the call (except for the version 


number, which must be supplied by the caller). 


changes the characters used for editing input. The info_ptr points 
to the following structure: : 


dcl 1 editing chars aligned, 


2 version fixed. bin, 

2 erase char (1) unaligned, 

2 kill ehar (1) unaligned; 
where: 


version is the version number of this structure. It must be 2. 


erase 


kill 


(Version 1 is used by network software. ) 
is the erase character. 


is the kill character. 


The following rules apply to editing characters: 


1. 
2% 


The two editing characters may not be the same. 


No carriage-movement character (carriage return, newline, 


horizontal tab, backspace, vertical tab, or formfeed) may be 


used for either of the editing functions. 
NUL and space may not be used for either editing function. 


If either of the editing characters is an ASCII control 
Character, it will not have the desired effect unless ctl_char 


mode is on. 


tty_ tty_ 


get_editing chars 
is used to find out what input editing characters are in effect. 
The info_ptr points to the structure described above for 
set_editing chars, which is filled in as a _ result of the call 
(except for the version number, which must be supplied by the 
caller). 


set_input_translation 
provides a table to be used for translation of terminal input to 
ASCII. The info_ptr points to a structure of the following form: 


del 1 translation_info aligned, 
2 version fixed bin, 
2 default fixed bin, 
2 table aligned, 
3 entries (0:127) char (1) unaligned; 
where: 
version is the version number of the structure. It must be 
Mee 
default indicates, if nonzero, that the default table for the 


current terminal type is to be used. If it is not 
zero, the remainder of the structure is ignored. 


The table is indexed by the value of a typed input character, and 
the corresponding entry contains the ASCII character resulting from 
the translation. If the info_ptr is null, no translation is to be 
done. 


NOTE: In the case of a terminal that inputs 6-bit characters 
and case-shift characters, the first 64 characters of 
the table correspond to characters in lower shift, and 
the last 64 to characters in upper shift. 


set_output_translation 
provides a table to be used for translating ASCII characters to the 
code to be sent to the terminal. The info _ptr points to a structure 
like that described for set_input_translation (above). The table is 
indexed by the value of each ASCII character, and the corresponding 
entry contains the character to be output. If the info_ptr is null, 
no translation is to be done. 


NOTE: For a terminal that expects 6-bit characters and 

ecase-shift characters, the 400(8) bit must be turned on 
in each entry in the table for a character that requires 
upper shift and the 200(8) bit must be on in each entry 
for a character that requires lower shift. 
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set_input_conversion 


provides a table to be used in converting input to identify escape 
sequences and certain special characters. The info_ptr points to a 
structure of the following form: 


del 1 conversion_info aligned, 
2 version fixed bin, 
2 default fixed bin, 
2 table aligned, 
3 entries © (0:127) fixed bin (8) unaligned; 
where: 
version is as above. 
default is as above. 


The table is indexed by the ASCII value of each input character 
(after translation, if any), and the corresponding entry contains 
one of the following values: | 2 


-- ordinary character 

-- break character 

escape character | 

-- character to be thrown away 

-- formfeed character (to be thrown away if page-length is nonzero) 


HEWN oO 
' 
I 


set_output_conversion 


—_ #3 4 £4«d od 
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provides a table to used in formatting output to identify certain 
kinds of special characters. The info_ptr points to a= structure 
like that described for set_input_conversion (above). The table is 
indexed by each ASCII output character (before translation, if any), 
and the corresponding entry contains one of the following values: 


-- ordinary character 

newline | 

-~ carriage return 

-- horizontal tab 

-- backspace 

vertical tab 

-- formfeed 7 7 

-- character requiring octal escape 

-- red ribbon shift 

-- black ribbon shift 

-- character does not change the column position 

-- this character together with the following one do not change 
the column position (used for hardware escape sequences) 
greater -- a character requiring a special escape sequence. The 
indicator value is the index into the escape table of the 
sequence to be used, plus 16. 


~~] 
Oo 
“3 
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get_input_translation 
get_output_translation 
get_input_conversion 
get_output_conversion 


set_special 
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These orders are used to obtain the current contents of the 
specified table. The info _ptr points to a structure like the one 
described for the corresponding "set" order above, which is filled 
in as a result of the call (except for the version number, which 
must be supplied by the caller). In the case of translation tables, 
if the specified table does not exist (no translation is required), 
the status code error_table_$no_table is returned. 


provides a table that specifies sequences to be substituted for 
certain output characters, and characters which are to be 
interpreted as parts of escape sequences on input. Output sequences 
are of. the following form: 


del 1 c_chars based aligned, 
2 count fixed bin (8) unaligned, 
2 chars (3) char (1) unaligned; 


where: 

count is the actual length of the sequence in characters 
(O<=count<=3). If count is zero, there is no 
sequence. 

chars are the characters that make up the sequence. 


The info_ptr points to a structure of the following form: 


del 1 special_chars aligned based, 
2 version fixed bin, 
2 default fixed bin, 
2 nl_seq aligned like c_chars, 
2 er_seq aligned like c_chars, 
2 bs_seqg aligned like c_chars, 
2 tab_seq aligned like c_chars, 
2 vt_seq aligned like c_chars, 
e ff_seq aligned like c_chars, 
2 printer_on aligned like c_chars, 
2 printer_ofrf aligned like c_chars, 
2 red_ribbon_shift aligned like c_chars, 
2 black_ribbon_shift aligned like c_chars, 
2 end_of_page aligned like c_chars, 
2 escape_length fixed bin, 
2 not_edited_escapes (0 refer (escape_length)) like c_chars, 
2 edited_escapes (0 refer (escape_length)) like c_chars, 
2 input_escapes aligned, 
3 len fixed bin (8) unaligned, 
3 str char (1 refer (input_escapes.len)) unaligned, 
2 input_results aligned, 
3 pad bit (9) unaligned, 
3 str char (1 refer (input_escapes.len)) unaligned; 
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where: 
version 


default 


nl_seq 


cr_seq 


bs_seq 


tab_seqg 
vt_seq 
ff_seq 
printer_on 


printer_off 


tty_ 


is the version number of this structure. It must be 


is as above. 


is the output character sequence to be substituted 
for a newline character. 


is the output character sequence to be substituted 
for a carriage-return character. If count is zero, 
the appropriate number of backspaces is substituted. 


is the output character sequence to be substituted 
for a backspace character. If count is zero, a 
carriage return and the appropriate number of blanks 
are substituted. | 


is the output character sequence to be substituted 
for a horizontal tab. If count is zero, the 
appropriate number of blanks is substituted. 


is the output character sequence to be substituted 
for a vertical tab. If count is zero, no characters 
are substituted. 


is the output character sequence to be substituted 
for a formfeed. If count is zero, no characters are 
substituted. 


is the character sequence to be used to implement the 
"printer_on" control operation. If count is zero, 
the function is not performed. 


is the character sequence to be used to implement the 
"printer_off" control operation. If count is zero, 
the function is not performed. 


red_ribbon_shift 


is the character sequence to be substituted for a red 
ribbon-shift character. If count is zero, no 
characters are substituted. 


black_ribbon_shift © 


end_of_page 


escape_length 


is the character sequence to be substituted for a 
black ribbon-shift character. If count is zero, no 
characters are substituted. 


is the character sequence to be printed to indicate 
that a page of output is full. 


is the number of output escape sequences in each of 
the two escape arrays. 


not_edited_escapes 


is an array of escape sequences to be substituted for 
particular characters if the terminal is in ""“edited" 
mode. This array is indexed according to the 
indicator found in the corresponding output 
conversion table. 
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edited_escapes 7 
: is an array of escape sequences to be used in 
"todited" mode. It is indexed in the same fashion as 
not_edited_escapes. 


input_escapes is a string of characters each of which forms an 
escape sequence when preceded by an escape character. 


input_results is a string of characters each of which is to replace 
the escape sequence consisting of an escape character 
and the character occupying the corresponding 
position in input_escapes (above). 


NOTE: nl_seq.count should generally be nonzero, 
as should either er_seq.count = or 
bs_seq.count. | 


get_special | 
is used to obtain the contents of the special_chars table currently 
in use. The info_ptr points to the following structure: | 


- del 1 get_special_info aligned, 
3 2 area_ptr ptr, 
2 table_ptr ptr; 


f~ | where: 


area_ptr points to an area in which a copy of the current 
special_chars table is returned. (Input) 


table_ptr is set to the address of the returned copy of the 
table. (Output) | 


Notes 


To assist the user in determining how to alter the tables described above, 
a summary is given below of the sequence of operations performed on input = and 
output strings in ring 0. : 


INPUT PROCESSING 


sae Translation 
The characters are translated from the terminal's code to ASCII, using 
the input_translation table. If there is no input_translation table, 
this step is omitted. 


ex Canonicalization 


The input string is rearranged (if necessary) into canonical form as 
foo | described in Section III of the MPM Reference Guide. 


3. Editing 


Erase and kill editing is carried out, using the editing chars string 
described above. 


2777 7-158.7 AK92B 


tty_ 


Break and escape processing 

The Characters in the input string are looked up in the 
input_conversion table and treated accordingly. If a character is 
preceded by an escape character (as determined from the table) it is 
looked up in the input_escapes array in the special_chars table, and, 
if found, replaced by the corresponding Character from the 
input_results array. 


OUTPUT PROCESSING 


2/77 


Capitalization 
Lowercase letters’ are replaced by uppercase for terminals in "capo" 
mode; uppercase letters are prefixed by escape characters if 


appropriate. 


Formatting 
The Characters ‘in the Output string are looked up in the 


“output_conversion table described above. Carriage-movement characters 


are replaced by sequences found in the special_chars table, followed 
by delay characters if so indicated by the delay table. Ribbon-shift 
Characters are likewise replaced by appropriate sequences. Any 
character whose indicator in the output_conversion table is greater 
than 16 is replaced by the (indicator-16)th sequence in either’ the 
not_edited_escapes or edited_escapes array in the special_chars table. 


Translation : .¢ | 
The result of step 2 is translated from ASCII to the terminal's code, 


using the output_translation table. If there is no output_translation 
table, this step is omitted. 
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Name: unwinder_ 


The unwinder_ subroutine is used to perform a nonlocal goto on the Multics 


stack. It is not intended to be called by direct programming (i.e., an explicit 


call statement in a program) but rather, by the generated code of a translator. 
For example, it is automatically invoked by a PL/I goto statement involving a 
nonlocal label variable. 


When invoked, the unwinder_ subroutine traces the Multics stack backward 
until it finds the stack frame associated with its label variable argument or 
until the stack is exhausted. In each stack frame it passes, it invokes’ the 
handler (if any) for the cleanup condition. When it finds the desired stack 
frame, it passes control to the procedure associated with that frame at the 
location indicated by the label variable argument. If the desired stack frame 
cannot be found or if other obscure error conditions arise (e.g., the stack is 
not threaded correctly), the unwinder_ subroutine signals the unwinder_error 
condition. If the target is not on the current stack, and there is a stack in a 
higher ring, that stack is searched after the current one is unwound. 


Usage 


declare unwinder_ entry (label); 


call unwinder_ (tag); 


where tag is a nonlocal label variable. (Input) 
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The majority of the vfile_ I/O module documentation is in Section III of 
the MPM Subroutines. The information given here describes additional order 
calls for users of indexed files. These orders allow a greater degree of 


control in the areas of synchronization and separate record/index manipulation. 


They implement various features of indexed files that require somewhat more 
knowledge of internal file structure than is expected of most users. 


min _block_size 


The min_block_size operation determines the minimum size for blocks of 
record space that are subsequently allocated by write_record or rewrite_record 
operations (documented in the iox_ subroutine). The specification remains in 
effect for the duration of the current opening or until another call to this 
order is issued. The I/O switch must be attached to an indexed file open for 
output or update. 


For this order, the info ptr argument must point to ae structure of the 
following form: 


del 1 min_blksz_info based(info_ptr), 
2 min_residue fixed bin(21), 
2min_capacity fixed bin(21); 


where: 


Ve min_residue specifies the minimum unused capacity of a record block 
(bytes); i.e., the difference between the record's length and 
the maximum length it can attain without requiring 
reallocation. (Input) | 


ee min capacity specifies the minimum total record capacity (bytes); i.e., 


the maximum length that the record can attain without 
requiring reallocation. (Input) 


When the 1/0 switch is initially opened, both these parameters are.set to zero. 


The current implementation imposes the following constraints on allocated 
record blocks: 


ie The minimum allocation is eight full words, including two header words 
for the block length and record length. The minimum nonnull record 
capacity is, therefore, 24 bytes. 


es The size of an allocated block is always an integral number of full 
words, i.e., a multiple of four bytes. 
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write_record or 


block_words 


otherwise, 


block_words 


record_status 
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below gives the allocation Size, block_words, used for a 
rewrite_record operation with a given buffer length, buff_len: 


= 0 (no allocation if and only if buff_len and min residue and 
min_capacity all are equal to 0) 


= max (8,(max(buff_len + min_residue, min_capacity) + 3) / 4) 


The record_status operation returns information about a specified record in 
an indexed file, and optionally permits the user to manipulate the record's lock 
and/or to allocate an empty record. | : | ts 


An argument 


is provided that permits the user to entirely avoid using the 


index in accessing and creating records (see "Notes" below). 


The I/O switch must be open and 


record position 


position is always set to the record 


indexed file. The next 
The current record 


attached to an 
used by this operation. 
referenced. | 


is not altered or 


‘The I/O switch must be open for output or update in order to lock, unlock, 
or create a record. ee he Sk 3 


For — 
following form: 


this order, the info_ptr 


argument must point to a structure of the 


based(info_ptr) aligned, 


del 1 rs_info 
2 version fixed bin, 
2 flags aligned, 
3 lock_sw bit(1) unal, 
3 unlock_sw bit(1) unal, 
3 create_sw bit(1) unal, 
3 locate_sw bit(1) unal, 
3 mbz1 bit(32) unal, 
2 record_len fixed bin(21), 
2 max_rec_len fixed bin(21), 
2 record ptr ptr, 
2 descriptor fixed bin(35), 
2 mbz2 fixed bin; 
del rs_info_version_1 static internal fixed bin init(1); 
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where: 


1. 


2. 


4, 


De 
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version 


lock_sw 


 unlock_sw 


create_sw 


locate_sw 
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is provided for compatibility with possible future versions 
of this info structure. The user should set this argument 
to rs_info_version_1. (Input ) 


indicates whether an attempt is made to lock the specified 
record within the wait time limit given at attachment or 
subsequently set via the set_wait_time order (documented in 
the MPM Subroutines). (Input) 

Wath yes 

"NONb no 


Possible error codes are: 

error_table_$invalid_lock_reset 
error_table_$locked_by_this_process 
error_table_$lock_wait_time_exceeded 
error_table_$no_room_for_lock 

The last code is returned if the allocated record block is 
too small to contain a lock. (See "Records Locks" below). 


indicates whether an attempt is made to unlock the record. 
(Input) 

"4b yes 

"O"b no 


Possible error codes are: 

error_table_$lock_not_locked 
error_table_$locked_by_other_process 
error_table_$no_room_for_lock 

If both lock_sw and unlock_sw are set to "1"b, the locking 
takes place first and determines the resultant error. code. 
(This permits one to clear an invalid lock in a single 
operation.) 


indicates whether a new record is allocated using the 
record_len and max_rec_len arguments as input parameters. 
(Input) 

"41th yes 

"WONb no 


The contents of the record are set to zero, and its lock is 
set in the same operation, if lock_sw equals "1"b, 
Depending upon the setting of locate_sw, the new record may 
be entered into the index. If locate_sw equals "0"b, the 
current key for insertion is added to the index as a key for 
the new record. Otherwise, no index entry is created and 
the key for insertion becomes undefined. 


indicates how the record of interest is located. (Input) 

"Ob if create_sw also equals "0"b, this indicates that 
the current record position defines the record of 
interest. Otherwise, the current key for insertion 


is used. If the relevant position designator is 
undefined, the code error_table_$no_record or 
error_table_$no_key is returned, whichever is 


appropriate. 
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record_len 


max_rec_len 


record_ptr 


descriptor 
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ae lo) if create_sw equals "O"b, this indicates that the 
descriptor argument is an input parameter defining 


the location of the record of interest. When such 
references are permitted in a shared file, users must 
observe certain protocols to ensure proper 


Synchronization of access at the record level. 
Record locks are provided for this purpose. If 
create_sw equals "1"b, this causes the new record to 
be created without a key. 


must be set to zero by the user. (Input) 


gives the record's length in bytes. (Output) If create_sw 
equals "1"b, this argument is input. 


if create_sw equals "i"b_ this argument is input and 
overrides any minimum block size specification that may. 
currently be in effect (see min _block_size order above). 
The returned value gives the maximum length that the record 
can attain (bytes) without requiring reallocation. When 
this argument is used as an input parameter, the resultant 
maximum record length is the smallest number greater than or 
equal to max_rec_len that corresponds to an implemented 
(nonzero) block size. (Output) | 


points to the first byte of the allocated record, or is. set 
to null if no allocated record exists. (Output) 


is a process independent locator for the specified record. 

This value is used as an input argument when locate _SW 
equals "1"b and create_sw equals "0"b. (Output) The actual 
structure of each descriptor is as follows: 


dcl 1 descrip struct based (addr(descriptor)) aligned, 
2 comp_num. fixed bin(17) unal, 
2 word_offset bit(18) unal; 


where: 


-comp_num is the multisegment file component number 
of the segment containing the record. 


word offset is the word offset of the block of storage 
| containing the allocated record, relative 
to the base of its file component. 


A zero aC ceon OF designates an unallocated (zero-length) 
record. | 


Descriptors may also be arguments to the add_key, 
delete_key, reassign_key, and get_key orders. Notice that 
at any given time within a single file each record is 
uniquely located by its descriptor, which remains valid only 
for the life of a single allocation. 
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Notes 


If locate sw is set to "1"b, the resultant current record position moves 
"outside" of the index in the sense that there is no key associated with the 
current record. This situation may also arise after using the delete_key 
operation; if so, a subsequent rewrite_record or delete_record operation 
behaves differently from the usual case. The difference is that no 
corresponding index entry is changed or deleted to reflect the change to the 
record. 


Extreme caution must be exercised when using the control operations that 
take a descriptor as an input argument, especially in a shared environment. The 
user is responsible for ensuring that previously obtained descriptors and 
pointers are still valid when they are used. Also, pains must be taken to 
maintain the index in a consistent state, i.e., each index entry should 
designate a valid record if a record reference may be attempted. 


get_key 


The get_key operation returns both the key and the record descriptor for 
the next record in an indexed file. 


The 1/0 switch must be open for keyed_sequential_input or 
keyed_sequential_update. If the next record position is at end of file, the 
code error_table_$end_of_info is returned. If the next record position is 
undefined, the code error_table_$no_record is returned. The next record 


position is unchanged, and the current record position is set to the next record 
if the operation is successful; otherwise, the current record position is set to 
null. 


For this order, the info _ptr argument must point to a structure of the 
following form: | 


del 1 get_key_info based (info_ptr), 


2 mbz fixed bin, 
2 descriptor fixed bin(35), 
2 key_length fixed bin, 
2 key_string char(0 refer(get_key_info.key_length) ) ; 
where: 
a descriptor is the record locator for the next record. This value may be 
used as an input argument to the control operations add_key, 
delete_key, reassign_key, and record_status (see "Notes" 


below). (Output) 


2% key_length is the length of the key at the next record position. 
| (Output) 


33 key_string is the next record's key. (Output) 


4, mbz must be set to zero by the user. (Input) 
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Notes 


The interpretation of the descriptor argument as a record locator is not 
mandatory, Since the add_key and reassign_key operations permit the user to set 
the descriptor portion of an index entry to an arbitrary 36-bit value. 


| The descriptor itself may be thought of as a one-word record that is read 
by the get_key operation. 


add_key 


| The add_key operation creates a new index entry with a given key and record 
descriptor. | | -— | 


The I/O switch must be open for direct_output, direct_update, 
keyed_sequential_output, or keyed_sequential_update. Current and next record 
positions are unchanged. | | 7 | 


Associations may be formed between any number of keys and a_ single record 
via this operation. Duplicate keys may be added if the file is attached with 
the -dup_ok control argument, or if the file already contains duplications; 
otherwise, the code error_table_$key_duplication is returned. (See "Duplicate 
Keys" below.) : | 


This operation, as well as the delete_key, reassign_key, and get_key orders 
do not reference the length or contents of a record. This permits one to avoid 
the use of actual records altogether in any given indexed file. | 


For this order, the info _ptr argument must point to a structure of the 
following form:. | 


del 1 add_key_info | based(info_ptr), 


2 flags aligned, 
3 input_key bit(1) unal, 
3 input_descrip bit(1) unal, 
3 mbz bit(34) unal, 
2 descriptor fixed bin(35), 
e key_length fixed bin, 
2 key_string char(0 refer (add_key_info.key_length)); 
where: 
Ve input_key indicates whether the new key is given in the info 


Structure. (Input) 

"ONDb indicates that the current key for insertion is the 
new Key. If this value is undefined, the code 
error_table_$no_key is returned. | 

BTED indicates that the key to be added is the key_string 
contained in this info structure. 
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Ze input_descrip indicates whether the new descriptor is given in the info 
| structure. (Input) | 
HOND indicates that the current record defines the new 
descriptor. If the current record is undefined, the 
code error_table_$no_record is returned. 
WD indicates that the user-supplied descriptor in this 
info structure is the new descriptor. : 


3% descriptor is used only if the variable input_descrip is set to "1"b. 

| The descriptor is stored into the index together with its 
associated key. Any 36-bit quantity may be_ supplied, 
although in general this number is a result of a previous 
record. status or get_key control operation. Descriptors are 
used by operation that reference the contents or length of a 
record, in order to obtain the record's address. (Input) 


4, key_length is the length of the key_string. Keys must be between 0 and 
. 256 characters, inclusive. (Input) 


5. key_string is used only if add_key_info.input_key is set to "1"b. It 
defines the key to be added to the index with the 
appropriate record descriptor. (Input) 


6. mbz must be set to zero by the user. (Input) 


delete_key 
The delete_key operation deletes a specified index entry. 


The I/O switch must be open for direct_update or keyed_sequential_update. 
The current and next file positions are left unchanged, with the following 
exception: if the deleted index entry is at the next record position, then the 
next record position is advanced to the following index entry, or becomes 
undefined in direct openings. 7 


For this order, the info_ptr argument may be null or may point to a 
structure of the following form: 


del 1 delete_key_info like add_key_info based (info_ptr); 


where: 


We input_key indicates whether the key is given in the info structure. 
(Input) 
nOMb indicates that the key associated with the current 
file position defines the key of the index entry that 
is to be deleted. If current position is undefined 
or outside the index (e.g., after deleting the 
current key of the current record), the code 
error_table_$no_key is returned. 
wpb indicates that the user-sSupplied key_string defines 
the key of the entry to be deleted. If no such key 
is found, the code error_table_$no_key is returned. 
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2% input_descrip indicates whether the descriptor is given in the info 
, Structure. (Input) 

"O"b indicates that the index entry to be deleted is 
associated with the current record. If the current 
record is undefined, the code error_table_$no_record 

— is returned. 
AD indicates that the entry to be deleted is associated 
with the user-supplied descriptor. If no such entry 
exists, the code error_table_$no_record is returned. 


3% descriptor is used only if delete_key_info.input_descrip equals "1"b. 
| The entry that is deleted is the first whose descriptor 
matches this value, among those entries with the specified 

key. (Input) 


4, key_length same as in the add_key_info structure above. (Input) 
5.  key_string . if delete_key_info.input_key equals "I"b, this argument 


defines the key for which the index entry with the specified 
record descriptor is to be deleted. (Input) 


If the info_ptr. argument is null, the index entry at the current file 
position is deleted, i.e., the effect is the same as that of setting both 
arguments, input_key and input_descrip, to "0"b. | 


reassign_key 


The reassign key operation causes the descriptor portion of a specified 
index entry to be replaced with a given value. | | 


| The I/O switch must be open for direct_update or keyed_sequential_update. 
The file position designators are not changed. | 7 - 


; For “this order, the info_ptr argument must point to a structure of the 
following form: ok , . oO 


del 1 reassign_key_info - based(info_ptr), 
2 flags © | aligned, 
3 input_key . bit (1) unal, 


3 input_old_descrip pbit(1) unal, 
3 input_new_descrip bit(1) unal, 


3 mbz bit(33) unal, 
2 old_deserip fixed bin(35), 
2 new_descrip fixed bin(35), 
2 key_length . | ' fixed bin, 
2 key_string char(0 refer(reassign_key_info.key_length) ); 
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where: 

1. input_key indicates whether the key is given in the info 
structure. (Input) 
tO" b indicates that the index entry to be reassigned 

has as its key the current key for insertion. 
If undefined, the code error_table_$no_key is 
returned. 

al iis 9) indicates that the key_string argument defines 
the key portion of the index entry to _ be 
reassigned. If the key_string is not found in 
the index, the code error_table_$no_key is 
returned. 

2. input_old_descrip indicates whether the old descriptor is given in the 
info structure. (Input) 

"OD indicates that the entry to be changed is 
associated with the current record. If the 
current record is undefined, the code 

error_table_$no_record is returned. 

ako) indicates that the old_descrip argument defines 
the descriptor portion of the index entry to be 
changed. 

3° input_new_descrip indicates whether the new descriptor is given in the 

, info structure. (Input) 

"OND indicates that the specified index entry is to 
be reassigned to the current record. If the 
current record is undefined, the code 
error_table_$no_record is returned. 

"1% indicates that the argument new_descrip is to 
supply the new value for the descriptor portion 

of the specified index entry. 

4, old_descrip is used only if reassign _key_info.input_old_descrip 
equals "1"b. The entry that is reassigned is the first 
whose descriptor matches this value, among those index 
entries with the specified key. (Input) 

ae new_descrip is used only if reassign _key_info.input_new_descrip 
equals "1"b. This value replaces the old descriptor of 
the specified index entry. (Input) 

6. key_length same as in the add_key_info structure above. (Input) 

Ts key_string if reassign_key_info.input_key equals wD: this 


argument defines the key for which the index entry with 
the specified descriptor is to be reassigned. (Input) 


set_file_lock 


The set_file_lock order is accepted when the I/O switch is open for output or 
update and attached to an indexed file with the -share control argument. For 
this order, the info_ptr argument must point to a variable of the following 
form: 


del set_lock_flag bit(2) aligned based(info_ptr) ; 
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This operation Causes the file to be _ locked (if possible within the 
wait-time limit) or unlocked, depending on whether the user has set the first 
bit of info_ptr->set_lock_flag to "I"b or "O"b, respectively. 


The possible error codes are: 


error_table_$locked_by_this_process 
error_table_$lock_wait_time_exceeded 
error_table_$lock_not_locked 
error_table_$locked_by_other_process 


The second bit of set_lock_flag indicates the class of Operations that are 
to be excluded by locking the file. If this bit is "O"b, only operations that 
alter the file are excluded (passive operations do not detect this state). 
Otherwise, all index referencing operations are excluded. In any case, the 
exclusion only applies to Operations outside the current opening. 7 


error_status 


The error_status order is accepted when the I/O switch is open and attached 
to an indexed or sequential file. The operation returns information about the 
most recent attempt to position beyond either end of file in the current 
opening. 


For. this order the info_ptr argument must point to a structure of the 
following form: 


error_info based(info_ptr), 


del 1 
2 version fixed, 
2 type — fixed, 
2 requested fixed(34), 
2 received fixed(34); 
where: 
tee version must be set to one by the user. (Input) 
2% type indicates the type of error that has occurred. (Output) 
0 no errors | 
1 attempt to position beyond end or beginning of file. 
a. requested | gives the value of the position skip argument that led to 
: the most recent error. (Output) 
4. received gives the actual number of records successfully skipped 


before encountering end or beginning of file (negative if 
backwards skip). (Output) 
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Record Locks 


This feature pertains only to indexed files. Record locks provide a basis 
for synchronizing concurrent access at the individual record level. The setting 
and clearing of record locks is explicitly controlled by the user via the 
record_status order. 


When the capacity of an allocated record block exceeds its contents by at 


least four bytes, the last word of the block is treated as a record lock. A 


nonzero lock identifies the process that set it. The user can ensure that 
record allocations leave room for a lock by using the min_block_size order with 
a residue specification of at least four bytes. 


All operations that reference the length or contents of an existing record 
(e.g., seek_key,. but not seek_head) also check the record's lock (if one 
exists). If the record is not locked, the operation proceeds normally. 
Otherwise, the returned error code reflects the state of the lock, indicating 
that the contents of the record may be in an inconsistent state. In this case, 
if the operation does not explicitly involve changing the file, it proceeds 
normally and the returned code is: error_table_$record_busy, if the record is 
locked by another live process; error_table_$lock_is_invalid, if the record's 
lock is set, but not by an | existing process; or 
error_table_$locked_by_this_process, if the record is locked in the caller's 
process. 


Attempting a rewrite_record or delete_record operation on a_ record locked 
by another process has no effect other than to return the code 
error_table_$record_busy (file is unchanged). If the lock is invalid, these 
operations return the _ code error_table_ $invalid_lock_reset and zero the lock. 
If the lock was set by the caller, the code returned is 
error_table_$locked_by_this_process. In either case, the operation is 
successful. 


When a record that is locked by the user's process is rewritten, its lock 
remains set, as long as the minimum block size specification currently in effect 
leaves enough room for a record_lock. 


All control orders can be performed using the io_call command. The general 
format is: 


io_call control switchname order -optional_args- 


where: 

ae order is any of the control operations supported by vfile_, 
or is one of the abbreviations listed below. 

ca optional_args are required for certain orders as indicated below. 
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or abbreviation arguments Output 
min_block_size, mb -min_res- Nothing is printed. 


-min_cap- 


where both arguments are integers that may optionally be omitted, in which 
case they default to zero. | | 3 


record_status, rs, rsb -flags- If abbreviation rsb is 
-recl- used, nothing is printed; 
-maxl- otherwise the record_length, 
-descrip- | max_rec_len, record_ptr, and 


record descriptor (in octal) 
are printed. 


where: 
13 flags ' is a string of four bits, corresponding to the switch 
settings for lock_sw, unlock_sw, create_sw, and locate_sw. 
This argument defaults to "0000"b if not given. 
2% recl is an integer that must be given when flags.create_sw is 
a set. This determines the new record length. 
oe maxl is an optionally supplied integer that may be given along 


with recl to specify a maximum record length. This defaults 
to recl if not given. 7 | 


4, descrip is an octal record descriptor required when flags.locate_sw 
4 is set and flags.create_sw is not set 


get_key_, gk No arguments The next record's key and 
3 descriptor (octal) are 
| printed. 
add_key, ak flags | Nothing is printed. 
-key- | 
-descrip- 
where: 
eg flags is a string of two bits corresponding to the switch settings 
for input_key and input_descrip. This argument is required. 
aa key isa character string that must be given if flags.input_key 
is set. | 
36: descrip | is an octal descriptor that must be Supplied if 
flags.input_descrip is set. 
delete_key, dk -flags- , Nothing is printed. 
7 -key- | 3 
-descrip- 


where args are the same as for add_key. Optionally, if no arguments are 
given, the operation is equivalent to a delete_key order with no info 
structure (null info_ptr). 


reassign_key, rk flags Nothing is printed. 
-key- 
-old_desc- 
-new_desc- 
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a 
where: 
Va flags is a string of three bits corresponding to the switch 
settings input_key, input_old_desc, input_new_desc. 
This argument is required. 
a key is a character string that must be given if 
flags.input_key is set. 
oe old_descrip is an octal number required if flags.input_old_dese is 
set. 
4, new_descrip is an octal number required if flags.input_new_dese is 
set. 
set_file_lock, sf set_lock_flag Nothing is printed. 
where set_lock_flag is a string of two bits, that must be specified. 
error_status, er "no arguments The requested and 
received counts are 
printed for the most 
recent skip error. 
_ : 
a 
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write_allowed_ write_allowed 
aa iAeasaaiNitig _ 


Name: write_allowed_ 


The write_allowed_ Subroutine determines whether a subject of specified 
authorization has access (with respect to the access isolation mechanism) to 
write an object of specified access class. 


Usage 
declare write_allowed_ entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned) ; 


returned_bit = write_allowed_ (authorization, access_class); 


where; 

lie authorization is the authorization of the subject. (Input) 

2. access_class is the access class of the object. (Input) 

3% returned_bit indicates whether the subject is allowed to write the 
object. (Output) 


"1"b write is allowed 
"Ob write is not allowed 
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APPENDIX A 


APPROVED CONTROL ARGUMENTS 


Many Multics commands take control argument strings, i.e., an argument 


whose first character is a minus sign (-). These character strings should be 


standardized as much as possible, not only for the convenience of the general 
user but also for those programmers writing their own commands. Two different 
lists of control arguments are presented on the following pages. Table A-1 
consists of general purpose control arguments, which are already used by several 
system commands and may be expected to cover most situations. Programmers 
writing their own commands (and system programmers) should use items from this 
list whenever possible. Table A-2 consists of more specialized control 
arguments, which cover a more limited range of situations. 


NOTE: Currently, not all Multics commands conform to the information 
provided in these lists. 


Table A-1. Approved Standard Control Arguments 
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-absentee -as 
-access_class -acc 
-~access_name -an 
-account 

-acl 

-address -addr 
-admin -am 
-after 

-alarm -al 
-all -a 
-arguments -ag 
-ascending -asc 
-assignments -asm 
-author -at 
-authorization -auth 
-bed 

-before 

-block -bk 
-branch | -br 
-brief -bf 
-brief_table -bftb 
-~call 

-category -cat 
-character -ch 
-check -ckK 
-comment -com 
-console_input -ci 
-COopy -Cp 
-count -ct 
-date -dt 
-date_time_contents_modified -dtcm 
-date_time_entry_modified -dtem 
-date_time_used -dtu 
-debug -db 
-decimal -de 
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Table A-1 (cont). 


-delete 
-delimiter 
-density 
-depth 
-descending 
-destination 
-device 
-directory 
~entry 

-every 
-exclude 
-execute 
-field 

-file 

-first 

-force 

-from 
-gen_type 
-~header 

-hold 
-home_dir 
~indent 
-input_file 
~input_switch 
-io_switch. 
-label 

-last 

-length 
~level 

-limit 
-line_length 
-lines 

-link 
-link_path 
-list 
-logical_volume 
-long 

-map 

-mask 

-match 

-mode 

-model 

-modes 
-multisegment_file 
-name 

-nl 

~nnl 
-no_address 
-no_header 
-no_offset 
~no_pagination 
-no_restore 
-no_update 
-number 
-octal 

-off 

-offset 

-on 

-optimize 
-ordered_field 
-outer_module 
-output_file 
-output_switch 
-owner 

-page 
-page_length 
-parameter 


Approved Standard Control Arguments 


-dl 
-dm 
-den 
-dh 
-dse 
-ds 
-dv 
-dr 
-et 
-eVv 
-eXx 


-fl 
-f 
-ft 


-~fm 
-gt 
-he 
-hd 
-hdr 
~ind 
-if 
-isw 
-i0SwW 
-lbl 
-1lt 
-ln 


-li 
-ll 
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Table A-1 (cont). 


<-pass 


-pathname 
-primary 
-print 
-profile 
-project 
-queue 
-quota 
-record 
-repeat 
-replace 
-request_type 
-reset 
-restart 
-reverse 
-ring 


-ring_brackets 


-search 
-section 
-segment 
~severity 
-short 

-sort 
-source 
-start 

-stop 
-subscriptrange 
-subsystem 
-symbols 
-system 
-table 

-~tabs 
-terminal_type 
-time 

-title 

-to 

-total 
-track 
-truncate 
-type 
-unique 
-~update 
-volume 
-wait 
-working dir 


Approved Standard Control Arguments 
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Table A-2. Approved Special Control Arguments 


-/punch 
~access_label 
-append 

-attached 
-attachments 

-ball 
-bottom_label 
-bottom_up 

-card | 
-change_default_auth 
-change_default_project 
~change_password 
-compile 

-continue 

-convert 

-cput 

-detach 

-dprint 

-dpunch 
-file_input 

-flush 

~format 
-~generate_password 
-Z£0O 
-govern 

-hyphenate 

-in | 
-input_description 
-interactive 
-interrupt 


einvisible | 


-keyed 

-library 

-lmargin 
~lower_case 

-mcc 

-meter 
-no_canonicalize 
-no_endpage 
-no_label 
-no_preempt 


--no_print_off 


-no_start_up 
-no_symbols 
-no_warning 

-nogo 

-out 
-output_description 
-print_off 
-process_overseer 
-raw 

-realt 

-remove 

-retain 
-retain_data 
-return_value 
-set_be | 
-set_nl 

-single 


 -Sleep 


-status 
-stop_proc 
-subtotal 
-tape 
~tape7 
-tape9 
-temp_dir 


-7p 
-albl 
-app 
-att 
-atm 
-bl 
-blbl 
-bu 


-cda 
-cdp 
-CDpW 


-ctu | 
-det 
~dp 
-dpn 
-fi 


-fmt 
-g&pw 


all <A 
-hph 


-ids 


-int 
-iv 
-lib 
-lm 
-le 


-mt 


-ncan . 


—nep 
-nlbl 
-np 
-nprf 


-ns 
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Table A-2 (cont). 


-template 
-timers 
-top_label 
-trace 
-~train 
-use_be 
-use_nl 
-watch 


Approved Special Control Arguments 
-tmp 
-tlbl 


-tn 
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INDEX 


access control (continued) 


A 


absentee 
arguments to absentee process 3-2 
assembly 
alm_abs 6-19 
CPU time limit 3-2 


absentee_real_init_admin_ 
see process: creation 


absolute 
see relocation information 


abs_io_ 3-2. 
ace format string 1-5 


access control 

access isolation mechanism (AIM) 
aim_check_$equal 7-5 
aim_check_$greater 7-5 
aim_check_$greater_or_equal 7-6 
convert_aim_attributes_ 7-17 
gét_privileges_ 7-48 
read_allowed_ {7-123 
read_write_allowed_ 7-160 
system_info_$access_ceiling 7-148 
system_info_$category_names 7-148 
system_info_$level_names 7-148 
write_allowed_ 7-160 

add ACL entry 
mbx_set_acl 6-34 
msf_manager_$acl_add 7-113 

delete ACL entry 
mbx_delete_acl 6-29 
msf_manager_$acl_delete 7-114 

initial ACL for new directories 
hes_$add_dir_inacl_entries 7-52 
hes_$delete_dir_inacl_entries. 7-57 
hes_$list.dir_inael 7-71 
hes_$replace_dir_inacl 7-77 

initial ACL for new segments 
hes_$add_inacl_entries 7-54 
hes_$delete_inacl_entries 7-58 
hes_$list_inacl 7-73 
hes_$replace_inacl 7-78 


list ACL 
mbx_list_acl 6-32 
msf_manager_$acl_list 7-111 
mailbox 
mbx_delete_acl 6-29 
mbx_list_acl 6-32 
mbx_set_acl 6-34 
multisegment file ACL 
msf_manager_$acl_add 7-113 
msf_manager_$acl_delete 7-114 
msf_manager_$acl_list 7-111 
msf_manager_$acl_replace 7-112 
privileges 
get_privileges_ 7-48 
replace ACL 
hes_$replace_dir_inacl 7-77 
hes_$replace_inacl 7-78 
msf_manager_$acl_replace 7-112 
rings 
get_ring 7-50 
hes_$get_dir_ring brackets 7-62 
hes_$get_ring brackets 7-65 
hes_$set_dir_ring brackets 7-79 
hes_$set_ring brackets 7-84 
set_ring_ brackets 6-44 


access isolation mechanism (AIM) 


access checking 
aim_check_$equal 7-5 
aim_check_$greater 7-5 
aim_check_$greater_or_equal 7-6 
access classes 
system_info_$access_ceiling 7-148 
system_info_$category_names 7-148 
system_info_$level_names 7-148 
effective access 
read_allowed_ 7-123 
read_write_allowed_ 7-160 
write_allowed_ 7-160 
privileges 
get_privileges_ 7-46 


accounting 


obtaining usage | 
system_info_$abs_prices 7-146 
system_info_$device_prices 7-145 
system_info_$io_prices 7-147 
system_info_$prices 7-144 

shift definition table 
system_info_$shift_table 7-14 


(continued) . 
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accounting (continued) argument_ptr 


Storage quota : 
posaiste eons =e see stack: frame 
hes_$quota_read 7-76 arithmetic 

conversion 
ACL i 
see access control Seinen. ee — 
| ASCII 
active function see character set 
argument list 
cu_$af_arg count 7-23 assembly 
cu_$af_arg ptr 7-24 alm 6-3 
cu_$af_return_arg 7-24 alm_abs 6-19 
error messages 
active_fne_err_ 7-3 | attach operation 


see I/O: operations 
active _function_error 
see condition: raising ATTN 
os see quit 
administrative access control | 
See access isolation mechanism (AIM) author 
see segment: author 
AIM 
see access isolation mechanism (AIM) authorization | 
; . see access isolation mechanism (AIM) 
alarm 
see time automatic storage 2-1 


allocation 
area : 
get_system_free_area_ 7-51 34 


alrm 
see condition: alrm 
bar_mode_sp 


any_other see stack: header 
see condition: any_other wes 
| | bind map | 
ap . see bound segment: bind map 
see register: pointer register 
O (PRO) | a. binding 
| see bound segment 
archive | 
sorting bit count | 
archive_sort 6-21 7 see multisegment file: bit count 


reorder_archive 6-40 
| bit count author 
area. see segment: bit count author 
free storage 
get_system_free_area_ 7-51 block 
see interprocess communication 
argument list 


absentee process 3-2 : | bound segment 1-27 
active function . : bind map 1-30 
cu_$af_arg count 7-23 . binder symbol block 1-29 
cu_$af_arg ptr 7-24 definition section 1-29 
cu_$af_return_arg 7-24 display_component_name 6-23 
descriptor 2-15 internal references 1-29 
examining print_bind_map 6-37 
cu_$arg_list_ptr 7-22 structure 1-27 
cu_$arg_ptr_rel 7-22 
decode_descriptor_ 7-35 break 
format 2-13 see quit: handling 
generating 
cu_$gen_call 7-26 break map 1-2 
cu_$ptr_ecall 7-26 
header 2-13 break point 1-2 
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brief mode 
login 3-3 


bulk I/0 
offline 
dprint_ 7-37 
iod_info_ $driver_access_name 7-94 
iod_info_$generic_type 7-94 
system_info_$io_prices 7-147 


byte 
see character set 


C 


call 
generating 2-10 
cu_$gen_call 7-26 
cu_$ptr_call 7-26 
short 2-10 


call operator 
see operator 


call_op_ptr 
see stack: header 


character set 
ascii_to_ebedic_ 7-7 
ebcdic_to_ascii_ 7-40 


cleanup 

bit count 
msf_manager_$adjust 7-110 

I/0 
iox_$destroy_iocb 7-96 

releasing stack frame 
unwinder_ 7-159 

translator temporary segment 
tssi_$clean_up_file 7-158 
tssi_$clean_up_segment 7-157 


clock 
see time 


close operation 
see I/O: operations 


closing 
multisegment file 
msf_manager_$close 7-110 


combined linkage region (CLR) 2-8 
print_linkage_usage 6-39 


command environment 
active function 
cu_$af_arg count 7-23 
cu_$af_arg_ ptr 7-24 
cu_$af_return_arg 7-24 
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command environment (continued) 

argument list 
cu_f$arg list_ptr 7-22 
cu_f$arg_ptr_rel 7-22 

command processor 
cu_$get_cp 7-27 
cu_$set_cp 7-27 

entry value 
cu_$decode_entry_value 7-30 
cu_$make_entry_value 7-30 
get_entry_name_ 7-45 

generating call 
cu_$gen_call 7-26 
cu_$ptr_call 7-26 

listener 
cu_$el 7-28 
cu_$get_cl 7-29 
cu_$set_cl 7-28 

ready message 
cu_$get_ready_mode 7-20 
cu_$get_ready_proc 7-20 
cu_$ready_proc 7-19 
cu_$set_ready_mode 7-21 
cu_$set_ready_proc 7-20 

stack frame 
cu_$stack_frame_ptr 7-25 
cu_$stack_frame_size 7-25 

system free storage 
get_system_free_area_ 7-51 

validation level 
cu_$level_get 7-30 
cu_$level_set 7-29 


comparison 
star name 
match_star_name_ 7-107 


component 
bound segment 
display_component_name 6-23 


com_err_ 4-7 


condition 3-2 

alrm 3-2 

any_other 3-2 

cput 3-2 

error messages 
active_fne_err_ 7-3 
condition_interpreter_ 7-14 
convert_status_code_ 7-18 
error_table_compiler 6-24 
find _condition_info. 7-42 

handling 
continue_to_Signal_ 7-125 
find_condition_info_ 7-42 
unwinder_ 7-159 

machine conditions 
prepare_mc_restart_$replace 7-121 
prepare_mc_restart_$retry 7-120 
prepare_mc_restart_$tra 7-121 

raising 
active_fne_err_ 7-3 
Signal. 7-125 


control operation 
see I/0: operations 
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convention 
equal 
get_equal_name_ 7-46 
Star 


check_star_name_$entry 7-12 
check_star_name_$path 7-12 


hes_¢star_ 7-87 
hes_$star_list_ 7-89 
match_star_name_ 7-107 


conversion 
access control 


convert_aim_attributes_ 7-17 


argument 
decode_descriptor_ 7-35 
bound segment offset 


display_component_name 6-23 


character set 
ascii_to_ebcdic_ 7-7 
ebcdic_to_ascii_ 7-40 
entry value 


cu_$decode_entry_value 7-30 
cu_$make_entry.value 7-30 


equal name 
get_equal_name_ 7-46 
general _ 
assign. 7-11 
location to name 
get_entry_name_ 7-45 
locator 


stu_$offset_to_pointer 7-137 
stu_$pointer_to_offset 7-138 


numeric to string 
assign 7-11 
ev_bin_ 7-32 
cv_bin_$dec 7-32 
cv_bin_$oct 7-33 

string to numeric 
assign. 7-11 
Cv_oct_ 7-34 | 

 @v_oct_check 7-34 


copying 
names | 
copy_names 6-22 
move_names 6-36 


cost-saving features 
absentee 


system_info_$abs_prices 7-146 
combining object segments 1-27 


program tuning | 
print_linkage_usage 6-39 


CPU 


time limit for absentee process 3-2. 


usage 


system_info_$abs_prices 7-146 
system_info_$prices 7-144 
timer_manager_$¢$cpu_call 7-152 


timer_manager_ 
$cepu_call_inhibit 7-153 


timer_manager_$cpu_wakeup 7-153 


timer_manager _ 
$reset_cpu_call 7-153 

timer_manager _ 
$reset_cpu_wakeup 7-153 


Pe 


Cput 
see condition: cput 


Create-if-not-found link 1-11 


creating 
data segment 1-12 
mailbox 
mbx_create 6-27 
multiple names 
mbx_add_name 6-26 


creation time of object segment 


1-2, 1-17 


D 


daemon 
offline I/0 
dprint_ 7-37 
iod_info_$driver_access_name 7-94 
iod_info_$generic_type 7-94 
system_info_$io_prices 7-147 


daemon_real_init_admin_ 
see process: creation 


data segment 1-1 
creating 1-12 


data-directed I/O 1-2 


debugging 1-2 

bound segment | 
display_component_name 6-23 
print_bind_map 6-37 

error messages | 
active_fne_err_ [7-3 
condition_interpreter_ 7-14 
convert_status_code_ 7-18 

linkage section 
print_linkage_usage 6-39 

stack trace 
cu_$stack_frame_ptr 7-25 
find_condition_info_ 7-42 

utilities 
stu_$decode_runtime_value 7-129 
stu_$find_block 7-127 
stu_$find_header 7-126 
stu_$find_runtime_symbol 7-128 
stu_$get_implicit_qualifier 7-130 
stu_$get_line 7-135 
stu_$get_line_no 7-133 
stu_$get_location 7-135 
stu_$get_runtime_address 7-131 
stu_$get_runtime_block 7-127 
stu_$get_runtime_line_no 7-134 
stu_$get_runtime_location 7-136 
stu_$get_statement_map 7-137 
stu_$offset_to_pointer 7-137 
stu_$pointer_to_offset 7-138 
stu_$remote_format 7-139 


AK9e2 


default error handling 
condition_interpreter_ 7-14 
continue_to_signal_ 7-125 
find _condition_info_ 7-42 
Signal_ 7-125 


default working directory 
get_default_wdir_ 7-44 


definition 
class three 1-9 
format 1-7 
implicit 1-26 


definition section 1-1, 1-5 
header 1-7, 1-25 
see also relocation information 


delete record operation 
see I/O: operations 


deleting 
ACL entries : 


hes _$delete_dir_inacl_entries 7-57 


hes_$delete_inacl_entries 7-58 
mbx_delete_acl 6-29 
msf_manager_$acl_delete 7-114 
directory 
hes _ $del_dir_tree 7-56 
initial ACL entries 


hes_$delete_dir_inacl_entries 7-57 


hes_$delete_inacl_entries 7-58 
mailbox 
mbx_delete 6-28 
mailbox ACL 
mbx_delete_acl 6-29 
multiple names 
mbx_delete_name 6-31 
search rules 
hes_$initiate_search_rules 7-69 


descriptor ; 
argument 2-15 
decode_descriptor_ 7-35 


detach operation 
see I/0: operations 


detach_iocb operation 
see I/0: operations 


directory 
access control 
hes_$get_dir_ring_ brackets 7-62 
hes_$set_dir_ring brackets 7-79 
ACL for new directories 
hes_$add_dir_inacl_entries 7-52 


hes_$delete_dir_inacl_entries 7-57 


hes_$list_dir_inacl 7-71 
hes_$replace_dir_inacl 7-77 
author | 
hes_$get_author 7-60 
default working 
get_default_wdir_ 7-44 
deleting 
hes_$del_dir_tree 7-56 
home 3-3 


i-5 


directory (continued) 
listing contents 
hes_$star_ 7-87 | 
hes_$star_list_ 7-89 
name manipulation 
copy_names 6-22 
move_names 6-36 
quota 
hes_$quota_move 7-75 
hes_$quota_read 7-76 
safety switch 
hes_$get_safety_sw 7-66 
hes_$set_safety_sw 7-85 
working 
get_default_wdir_ 7-44 


discretionary access control 
see access control 


dynamic linking 
see linking (interprocedure) 


E 


EBCDIC 
see character set 


entry operator 2-10 


entry point 
bound 
see segment: entry point bound 
name 
get_entry_name_ 7-45 
status 
print_link_info 6-38 


entry sequence 1-3, 1-24 


entry value 
conversion to pointer 
cu_$decode_entry_value 7-30 
generation from pointer 
cu_$make_entry_value 7-30 


entryname 
conversion from equal name 
get_equal_name_ 7-46 
match with star name 
match _star_name_ 7-107 


entry_op_ptr 
see stack: header 


entry_ptr 
see stack: frame 


equal convention 
get_equal_name_ 7-46 


error handling 
active_fne_err_ [7-3 
condition_interpreter_ 7-14 
(continued) 
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error handling (continued) 
convert_status_code_ 7-14 
error_table_compiler 6-24 
find_condition_info_ 7-42 
Signal. 7-125 


error_output 
see I/O: attachment 


event channel 
See interprocess communication 


exec_com 3-3 

expression word 1-10 

external symbol 1-5, 2-10 
elimination by binder 1-29 


name 
get_entry_name_ 7-45 


F 


fault 
see condition 


fault tag two (FT2) 1-14 


feb 
see file control block 


file (multisegment) 
see multisegment file 


file control block 
msf_manager_$close 7-110 
msf_manager_$open 7-108 
tssi_$clean_up_file 7-158 
tssi_$finish_file 7-157 
tssi_$get_file 7-155 


first reference trap 1-15 


free storage | 
get_system_free_area_ 7-51 


G 


gate 
entry point transfer vector 1-4 


get_chars operation 
see I/O: operations 


get_line operation 
see I/O: operations 


i-6 


H 


handling 
see condition 


hardware 
faults 
see condition 
machine language 
alm 6=3 
alm_abs 6-19 
registers 
see register 


home directory 3-3 


I/0 | 
attach description 4-3, 4-7 
attachment 3-2 
cleanup | 
iox_$destroy_iocb 7-96 
control block 4-4 
iox_$find_iocb_n 7-97 
iox_$look_iocb 7-97 
structure 4-2 
data-directed 1-2 
error messages 
active_fne_err_ [7-3 
condition_interpreter_ 7-14 
iox_$err_not_attached 7-96 
 iox_$err_not_closed 7-96 
iox_$err_not_open 7-96 
iox_$err_no_operation 7-96 
offline (daemon) 
dprint_ 7-37 | 
iod_info_$driver_access_name 7-94 
iod_info_$generic_type 7-94 
system_info_$io_prices 7-147 
open data 4-4 
open description 4-3, 4-8 
operations 4-2, 4-7, 4-8, 4-9 
synonym attachment 4-4, 4-6 
iox_$propagate 7-98 


information 
see status 


initial command line 3-3 


initial procedure 
see process overseer 


initproc 
see process overseer 


internal static offset table 
(ISOT) 2-8 
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internal static storage 
see static storage 


internal storage 1-2, 1-14, 1-26 


interprocess communication 
- event channel creation 
ipe_$create_ev_chn 7-99 
ipe_$dcel_event_call_channel 7-100 
ipe_$decl_ev_wait_chn 7-101 
event channel deletion 
ipe_$delete_ev_chn 7-100 
event channel management 
ipe_$cutoff 7-102 
ipe_$drain_chn 7-101 
ipe_$mask_ev_calls 7-103 
ipe_$read_ev_chn 7-105 
ipe_$reconnect 7-102 
ipe_$set_call_prior 7-103 
ipe_$set_wait_prior 7-102 
ipe_$unmask_ev_calls 7-104 
request wakeup 
timer_manager_$alarm_wakeup 7-152 
timer_manager_$cpu_wakeup 7-153 
timer_manager_ 
¢reset_alarm_wakeup 7-154 
timer_manager_ 
$reset_cpu_wakeup 7-153 
send wakeup 
hes_$wakeup 7-93 
wait for wakeup 
ipe_$block 7-104 
timer_manager_$sleep 7-151 


interrupt 
communication 
see interprocess communication 
suspend execution 
see condition 


intersegment reference 
see linking (interprocedure) 


interuser communication 

mailbox commands 
mbx_add_name 6-26 
mbx_ create 6-27 
mbx_delete 6-28 
mbx_delete_acl 6-29 
mbx_delete_name 6-31 
mbx_list_acl 6-32 
mbx_rename 6-33 
mbx_set_acl 6-34 

see also interprocess communication 


iocb 
see I/0: control block 


iox_$destroy_iocb 4-2 
iox ¢$find_iocb 4-2 


iox_$propagate 
r~ see I/O: synonym attachment 


ISOT 
see internal static offset 
table (ISOT) 


—i-7 


isot_ptr 
see stack: header 


L 


languages 

absentee compilation 
alm_abs 6-19 

assemblers 
alm 6-3 

command language 
see command environment 

status table 
error _table_compiler 6-24 

translator utilities 
tssi_$clean_up_file 7-158 
tssi_$clean_up_segment 7-157 
tssi_$finish_segment 7-156 
tssi_$get_file 7-155 
tssi_$get_segment 7-155 


length of segment 
see segment: length 


libraries 
search rules 
hes_$get_search_rules 7-68 
hes_$initiate_search_rules 7-69 


link 

author | 
hes_$get_author 7-60 

name manipulation 
copy_names 6-22 
move_names 6-36 

status 
hes_$star_ 7-87 
hes_$star_list_ 7-89 


linkage offset table (LOT) 2-7 


linkage section 1-2, 1-13, 1-26, 2-7 
header 1-13 


linking (interprocedure) 1-1 
1-14, 1-26 
elimination by binder 1-29 
linkage pointer 


generation by entry operator 2-10 


printing linkage section map 
print_linkage_usage 6-39 
printing object segment linkage 
print_link_info 6-38 
self-referencing link 1-10 
type 6 link 
initialization structure 1-13 


listener 
called by 
standard_default_handler_ 3-2 
cu_$el 7-28 
cu_$get_el 7-29 
cu_$set_cl 7-28 
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listing 
directory contents 
hes_$star_ 7-87 
_ hes_$star_list_ 7-89 
initial ACL for new directories 
hes_$list_dir_inacl 7-71 
initial ACL for new segments 
hes_$list_inacl 7-73 
mailbox ACL 
mbx_list_acl 6-32 
multisegment file ACL 
msf_manager_$acl_list 7-111 


listing segment 

translator interface 
tssi_$clean_up_ file 7-158 
tssi_$clean_up_segment 7-157 
tssi_$finish_file 7-157 
tssi_$finish_segment 7-156 
tssi_$get_file 7-155. 
tssi_$get_segment 7-155 


login 3-1 


login responder 
see process overseer 


LOT 
see linkage offset table (LOT) 


lot_ptr 
see stack: header 


1p | 
see register: pointer register 
4 (PRA) 


machine conditions 
examining 
find_condition_info_ 7-42 
restarting | 3 
prepare_mc_restart_$replace 7-121 
prepare_mc_restart_$retry 7-120 
prepare_mc_restart_$tra 7-121 


machine language 1-2 
alm 6-3 
alm_abs 6-19 


mailbox | 

access control 
mbx_delete_acl 6-29 
mbx_list_acl 6-32 
mbx_set_acl 6-34 

creating , 
mbx_create 6-27 

deleting 
mbx_delete 6-28 

name manipulation 
mbx_add_name 6-26 
mbx_delete_name 6-31 
mbx_rename 6-33 


i-8 


messages 
error 
active_fne_err_ 7-3 
condition_interpreter_ 7-14 
convert_status_code_ 7-18 
error_table_ compiler 6-24 
find_condition_info_ 7-42 
message of the day 3-3 
ready 
cu_$get_ready_mode 7-20 
cu_$get_ready_proc 7-20 
cu_$ready_proc 7-19 
cu_$set_ready_mode 7-21 
cu_$set_ready_proc 7-20 


mode 
see access control 


modes operation 
see I/O: operations 


moving 

names 
copy_names 6-22 
move_names 6-36 


multiple names 


creating 
mbx_add_name 6-26 
otc 
mbx_délete_name 6-31 
moving 


copy_names 6-22 
move_names 6-36 


multisegment file 
access control 
msf_manager_$acl_add 7-113 
msf_manager_$acl_delete 7-114 
msf_manager_$acl_list 7-111 
msf_manager_$acl_replace 7-112 
bit count 
msf_manager_$adjust 7-110 
msf_manager_$open 7-108 
closing 
msf_manager_$close 7-110 
finding next component 
msf_manager_$get_ptr 7-109 
opening | 
msf_manager_$open 7-108 


name 
access class 
system_info_$category_names 7-148 | 
system_info_$level_names 7-148 
copying 
copy_names 6-22 
move_names 6-36 
equal | 
get_equal_name_ 7-46 
(continued) 
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name (continued) 
external symbol (entry point) 
get_entry_name_ 7-45 
print_link_info 6-38 
installation 
system_info_$installation_id 7-142 
system_info_$titles 7-142 
mailbox 
mbx_add_name 6-26 . 
mbx_ delete_name 6-31 
mbx rename 6-33 
moving 
copy_names 6-22 
move_names 6-36 
reference 1-11 
star 
check _star_name_$entry 7-12 
check _star_name_$path 7-12 
hes_$star_ 7-87 
hes_$star_list_ 7-89 
match _star_name_ 7-107 
system version 
system_info_$sysid 7-142 


new_proc 3-1 


next_stack_frame_ptr 
see stack: frame 


nonlocal transfer 
unwinder_ 7-159 


no_start_up attribute 3-3 


O 


object map 1-2, 1-22 


object segment 1-1, 1-19 

creation time 1-17 

format 1-1 

Status 
display_component_name 6-23 
object_info_$brief 7-115 
object_info_$display 7-115 
object_info_$long 7-116 
print_bind_map 6-37 
print_link_info 6-36 

symbol table 
stu_$decode_runtime_value 7-129 
stu_$find_block 7-127 
stu_$find_header 7-126 
stu_$find_runtime_symbol 7-128 
stu_$get_implicit_qualifier 7-130 
stu_$get_line 7-135 
stu_$get_line_no 7-133 
stu_$get_location 7-135 
stu_$get_runtime_address 7-131 
stu_$get_runtime_block 7-127 
stu_$get_runtime_line_no 7-134 
stu_$get_runtime_location 7-136 
stu_$get_statement_map 7-137 
stu_$offset_to_pointer 7-137 


Si 


object segment (continued) 
stu_$pointer_to_offset 7-138 
stu_$remoce_format 7-139 

translator interface 

tssi_$clear up_file 7-158 
tssi_$clean_up_segment 7-157 
tssi_$finish file 7-157 
tssi_$finish segment 7-156 
tssi_$get_file 7-155 
tssi_$get_segment 7-155 


on_unit_rel_ptr 
see stack: frame 


open operation 
see I/0: operations 


opening 
multisegment file 
msf_manager_$open 7-108 


operator 2-10 
call 2-10 
entry 2-10 
push 2-11 
return 2-11 
short return 2-11 
short_call 2-10 


operator_link_ptr 


see stack: frame 


operator_return_offset 
see stack: frame 


ordering archive components 
see sorting 


p 


parameter 
descriptor 1-3 


per-process data 
linkage section 1-2 
stack 2-1 


PIT 
see process initialization 
table (PIT) 


pli_operators_ptr 
see stack: header 


pointer register 
see register 


position operation 
see I/0: operations 


prelinking 
bound segment 1-29 
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prev_stack_frame_ptr 
see stack: frame 


prices 
System_info_$abs_prices 7-146 
System_info_$device_prices T=-145 
System_info_$io_prices 7-147 
System_info_$prices 7-144 


printing 
offline 
dprint_ 7-37 
iod_info_$driver_access_ name 7-94 
iod_info_$generic_type 7-94 
System_info_$io_prices 7-147 


privileges 
see access isolation mechanism (AIM) 


procedure segment 
see object segment 


process 
access privileges 
get_privileges_ 7-48 
creation 3-1 
synchronization 
see interprocess communication 


process initialization table (PIT) 3-1 
process overseer 3-1 


protection rings 
see rings 


punched cards 
offline output 
dprint_ 7-37 | 
iod_info_$driver_access_name 7-94 
iod_info_$generic_type 7-94 
system_info_$io_prices 7-147 


pure procedure 
see object segment 


push_op_ptr 
see stack: header 


put_chars operation 
see I/0: operations 


Q 


queue . 
absentee 
alm_abs 6-19 
I/O daemon 
dprint_ 7-37 
system_info_$io_prices 7-147 


quit 3-3 

abort execution 
Signal 7-125 
unwinder_ 7-159 

enabling 3-3 

handling 3-3 
continue_to_signal_ 7-125 
find_condition_info_ 7-42 


quit_enable order 
see quit: enabling 


quota 
storage 
hes_$quota_move 7-75 
hes_$quota_read 7-76 


ready messages 
cu_$get_ready_mode 7-20 
cu_$get_ready_proc 7-20 
cu_$ready_proc 7-19 
cu_$set_ready_mode 7-21 
cu_$set_ready_proc 7-20 


read_key operation 
see I/0: operations 


read_length operation 
see I/O: operations 


read_record operation 
see I/O: operations 


reference name 1-11 


referencing dir 
hes_$get_search_ rules 7-68 


hes_$initiate_search_rules 7-69 


register 
machine conditions 


condition_interpreter_ 7-14 


find_condition_info_ 7-42 


prepare_mc_restart_$replace 7-121 
prepare_mc_restart_$retry 7-120 


prepare_mc_restart_$tra 7-121 


pointer register 0 (PRO) 
operator segment pointer 
2-10, 2-13 
pointer register 4 (PR4) 


linkage pointer 2-10, 2-13 


pointer register 6 (PR6) 
stack frame pointer 2-13 

pointer register 7 (PRT) 
stack base pointer 2-13 

Saving registers 2-10, 2-11 


relocation information 1-2, 1-20, 


text section 1-24 
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1-25 


rs 


renaming 
mailbox 
mbx_rename 6-33 


restarting 
fault 
prepare_mc_restart_$replace 7-121 
prepare_mc_restart_$retry 7-120 
prepare_mc_restart_$tra 7-121 


return_op_ptr 
see stack: header 


return_ptr 
see stack: frame 


rewrite_record operation 
see I/0: operations 


rings 2-1 

access control (ring brackets) 
hes_$get_dir_ring brackets 7-62 
hes_$get_ring brackets 7-65 
hes_$set_dir_ring brackets 7-79 
hes_$set_ring brackets 7-84 
set_ring brackets 6-44 

execution 
get_ring 7-50 
hes_$get_dir_ring brackets 7-62 
hes_$get_ring brackets 7-65 

validation level 
cu_$level_get 7-30 
cu_$level_set 7-29 


runtime operators 
see operator 


runtime symbol table 
see symbol table 


— 


safety switch 
see segment: safety switch 


sb 
see register: pointer register 


7 (PR7) 


sct_ptr 
see stack: header 


search rules 
home_dir 3-3 
obtaining 
hes_$get_search_rules 7-68 
setting 
hes_$initiate_search rules 7-69 


seek_ key operation 
see I/0: operations 


segdef 
see external symbol 


‘segment 


access control 
hes_$get_ring_ brackets 7-65 
hes_$set_ring_brackets 7-84 
set_ring brackets 6-44 

ACL for new segments 
hes_$add_inacl_entries 7-54 
hes_$delete_inacl_entries 7-58 
hes_$list_inacl 7-73 
hes_$replace_inacl 7-78 

author 
hes_$get_author 7-60 

bit count author 
hes_$get_bec_author 7-61 

entry point bound 1-4 
hes_$set_entry_bound 7-80 
hes_$set_entry_bound_seg 7-81 

length 7 
print_link_info 6-38 

maximum length 
hes_$get_max_length 7-63 
hes_$get_max_length_seg 7-64 
hes_$set_max_length 7-82 
hes_$set_max_length_seg 7-83 

name manipulation 
copy_names 6-22 
move_names 6-36 

safety switch 
hes_$get_safety_sw 7-66 
hes_$get_safety_sw_seg 7-67 
hes_$set_safety_sw 7-85 
hes_$set_safety_sw_seg 7-86 


self-referencing link 1-10 


self-relative 
see relocation information 


seven-punch cards 
dprint_ 7-37 


shift 
accounting 
system_info_$shift_table 7-146 


short_return_op_ptr 
see stack: header 


shutdown 
last system shutdown 
system_info_$last_shutdown 7-147 
next system shutdown 
system_info_$next_shutdown 7-144 


Signal_ptr 
see stack: header 


sorting 
archive 
archive_sort 6-21 
reorder_archive 6-40 


source map 
see object segment 


AK92 


Sp 
see register: pointer register 
6 (PR6) 


Special directories | 

default working directory 
get_default_wdir 7-44 

home directory 3-3 

search rules 
hes_$get_search_rules 7-68 
hes_$initiate_search_ rules 7-69 

working directory 
get_default_wdir 7-44 


Stack 2-1 

examining frame 
Stu_$decode_runtime_value T-129 
stu_$find_runtime_symbol 7-128 
Sstu_$get_implicit_qualifier 7-130 
stu_$get_runtime_address T=-131 
Stu_$get_runtime_block 7-127 
Sstu_$offset_to_pointer 7-137 
Stu_$pointer_to_offset 7-138 
stu_$remote_format 7-139 

frame 1-24, 2-1, 2-5, 211° 
creating 2-11 

frame pointer 
cu_$stack_frame_ptr 7-25 

frame size 
cu_$stack_frame_size 7-25 

header 2-1, 2-2, 2-11 

releasing frame 
unwinder_ 7-159 


Stack_begin_ptr 
see stack: header 


stack_end_ptr 
see stack: header 


standard_default_handler_ 3-2 | 


star convention _ 
check_star_name_$entry 7-12 
check_star_name_$path 7-12 
get_equal_name_ 7-46 
hes_$star_ 7-87 
hes_¢$star_list_ 7-89 
match_star_name_ 7-107 


start_up.ec 3-3 


Statement map | 
Stu_$get_statement_map 7-137 


Static section 1-2, 1-13, 
print_linkage_usage 6-39 


1-27 


static storage 1-2 


static_ptr 
see stack: frame 


status 
access control 
msf_manager_$acl_list 7-111 


Status (continued) 

directory 
hes_$get_author 7-60 
hes_$get_dir_ring brackets 7-62 
hes_$get_safety_sw 7-66 
hes_$quota_read 7-76 

directory contents 
hes_$star_ 7-87 
hes_$star_list_ 7-89 

messages 
active_fne_err_ 7-3 
condition_interpreter_ 7-14 
convert_status_code_ 7-18 
error_table_compiler 6-24 

object segment 
object_info_$brief 7-115 
object_info_$display 7-115 
object_info_$long 7-116 

segment 
hes_$get_author 7-60 
hes_$get_bc_author 7-61 
hes_$get_max_length 7-63 
hes_$get_max_length_seg 7-64 
hes_$get_ring brackets 7-65 
hes_$get_safety_sw 7-66 
hes_$get_safety_sw_seg 7-67 

system information 
System_info_$abs_prices 7-146 
system_info_$device_prices 7-145 
system_info_$installation_id 7-142 
System_info_$io_prices 7-147 
system_info_$last_shutdown 7-147 
system_info_$next_shutdown 7-144 
system_info_$prices 7-144 
system_info_$shift_table 7-146 
system_info_$sysid 7-142 
system_info_$timeup 7-143 
system_info_$titles 7-142 

 System_info_$users 7-143 


storage 


automatic 2-1 
based 

get_system_free_area_ 7-51 
Static 2-8 


storage quota 
hes_$quota_move 7-75 
hes_$quota_read 7-76 


Subroutine 
calling 2-9 
cu_$gen_call 7-26 
cu_$ptr_call 7-26 


Subsystem 3-1 


symbol block 1-2 
binder 1-29 
header 1-17 
Symbol section 1-17, 1-27 
symbol table 
using | 
stu_$decode_runtime value 7-129 
stu_$find_block 7-127 
(continued) 
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~/ 


symbol table (continued) 
stu_$find_header 7-126 
stu_$find_runtime_symbol 7-128 
stu_$get_implicit_qualifier 7-130 
stu_$get_line 7-135 | 
stu_$get_line_no 7-133 
stu_$get_location 7-135 
stu_$get_runtime_address 7-131 
stu_$get_runtime_block 7-127 
stu_$get_runtime_line_no 7-134 
stu_$get_runtime_location 7-136 
stu_$get_statement_map 7-137 
stu_$offset_to_pointer 7-137 
stu_$pointer_to_offset 7-138 
stu_$remote_format 7-139 


symbol tree i-2 
symbolic offset 1-11 


symbol _table 
see definition: implicit 


synonym 
see I/O: synonym attachment 


system information 
see status: system information 


T 


temporary storage 
see stack: frame 


text section 1-1 


time , 
last system shutdown 
system_info_$last_shutdown 7-147 
next system shutdown 
system_info_$next_shutdown 7-144 
process CPU usage 3-2 
system_info_$abs_prices 7-146 
system_info_$prices 7-144 
timer_manager_$cpu_call 7-152 
timer_manager _ 
$cpu_call_inhibit 7-153 
timer_manager_$cpu_wakeup 7-153 
timer_manager _ 
$reset_cpu_call 7-153 
timer_manager _ 
$reset_cpu_wakeup 7-153 
real time 3-2 
system_info_$prices 7-144 
timer_manager_$alarm_call 7-151 
timer_manager_ 
g$alarm_call_inhibit 7-152 
timer_manager_$alarm_wakeup 7-152 
timer_manager _ 
$reset_alarm_call 7-154 
timer_manager_ 
$reset_alarm_wakeup 7-154 
system startup time 
system_info_$timeup 7-143 


translators 

storage system 
tssi_$clean_up_file 7-158 
tssi_$clean_up_segment 7-157 
tssi_$finisn_file 7-157 
tssi_$finish_segment 7-156 
tssi_$get_file 7-155 
tssi_$get_sezment 7-155 

version number 1-2, 1-17 


trans_op_tv_ptr 
see stack: header 


trap pair 1-12 
tty_ 3-2 


type 6 link 
initialization structure 1-13 


type pair 1-10 


U 


unclaimed signal 


see condition: any_other 
unsnapped link 1-14 


unwinder_ptr 
see stack: header 


user 
parameters 3-1 
get_privileges_ 7-48 


user_i/o 
see 1/0: attachment 


user_info_ 3-1 


user_input 
see [/0: attachment 


user_output 
see I/0: attachment 


user_real_init_admin_ 
see process: creation 


V 


validation level 
directory 
hes_$get_dir_ring_ brackets 7-62 
hes_$set_dir_ring brackets 7-79 
obtaining 
cu_$level_get 7-30 
(continued) 


AK92 


validation level (continued) 
segment 
hes_$get_ring brackets 7-65 


hes_$set_ring brackets 7-84 
Setting 


cu_$level_set 7-29 
version of translator 1=2 


V_proceSsS_overseer attribute 
see process overseer 


WwW 


wakeup 

process CPU usage 
timer_manager_$cpu_wakeup 7-153 
timer_manager _ 

$reset_cpu_wakeup 7-153 

real time | | 
timer_manager_$alarm_wakeup 7-152 
timer_manager _ 
$reset_alarm_wakeup 7-154 

see also interprocess communication 


working directory 


default 


get_default_wdir 7-44 
search rules 


hes_$get_search_ rules 7-68 


hes_$initiate_search rules 7-69 


write_record operation 


see I/0: 


Operations 
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